@sendinel/mcp-server 1.0.139 → 1.0.140

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/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';
@@ -882,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',

package/build/tools/contacts.js

@@ -1,3 +1,4 @@
+import { dbErrorResult } from '../lib/db-errors.js';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
 import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
@@ -1253,133 +1254,138 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             utm_term: z.string().optional(),
         },
     }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
-        email = email.trim().toLowerCase();
-        const projectId = getProjectId();
-        // Block distribution list / system addresses
-        const DISTRO_LOCAL_PARTS = new Set(['all', 'everyone', 'distro', 'broadcast', 'announce', 'postmaster', 'abuse', 'mailer-daemon', 'bounce', 'bounces', 'noreply', 'no-reply', 'nobody', 'null', 'void']);
-        const DISTRO_PATTERNS = [/^all[-+.]/, /[-+.]all$/, /^list[-+.]/, /[-+.]list$/, /[-+.]announce$/, /^announce[-+.]/, /[-+.]distro$/, /^distro[-+.]/, /[-+.]broadcast$/, /^broadcast[-+.]/];
-        const local = email.trim().toLowerCase().split('@')[0] ?? '';
-        if (DISTRO_LOCAL_PARTS.has(local) || DISTRO_PATTERNS.some(p => p.test(local))) {
-            return contactInputError('validation_failed', `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.`);
-        }
-        // Validate project ownership before the cap, and reuse the double opt-in lookup.
-        const { data: siteInfo, error: siteError } = await db().from('sites')
-            .select('double_opt_in').eq('id', site_id).eq('project_id', projectId).maybeSingle();
-        if (siteError)
-            throw new Error(`Site lookup failed: ${siteError.message}`);
-        if (!siteInfo)
-            return contactInputError('not_found', 'Site not found for this project.');
-        const needsConfirm = siteInfo.double_opt_in === true;
-        const limit = await checkPlanLimit('contacts');
-        if (!limit.allowed) {
-            return contactInputError('plan_limit', contactLimitMessage(limit));
-        }
-        const embedOk = await hasCompaniesEmbed(projectId);
-        const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
-        let { data: existingContact, error: lookupError } = await db()
-            .from('subscribers')
-            .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
-            .eq('project_id', projectId)
-            .eq('email', email)
-            .maybeSingle();
-        if (lookupError)
-            return txt(`Error looking up contact: ${lookupError.message}`);
-        let customProperties;
-        if (company_name || company_domain) {
-            const orgId = await getProjectOrgId(projectId);
-            customProperties = await normalizeMcpContactPropertyPatch({
-                ...(company_name ? { company_name } : {}),
-                ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
-            }, { orgId, projectId });
-        }
-        const selection = embedOk ? '*, company:companies(id, name, domain)' : '*';
-        let contact;
-        if (!existingContact) {
-            const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
-            if (customProperties)
-                row.custom_properties = customProperties;
-            if (!needsConfirm)
-                row.opted_in_at = new Date().toISOString();
-            if (utm_source)
-                row.utm_source = utm_source;
-            if (utm_medium)
-                row.utm_medium = utm_medium;
-            if (utm_campaign)
-                row.utm_campaign = utm_campaign;
-            if (utm_content)
-                row.utm_content = utm_content;
-            if (utm_term)
-                row.utm_term = utm_term;
-            const { data, error } = await db().from('subscribers')
-                .upsert(row, { onConflict: 'project_id,email', ignoreDuplicates: true })
-                .select(selection).maybeSingle();
-            if (error)
-                return txt(`Error creating contact: ${error.message}`);
-            contact = data;
-            if (!contact) {
-                // A concurrent add won the unique key; its provenance belongs to that insert.
-                const result = await db().from('subscribers')
-                    .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
-                    .eq('project_id', projectId).eq('email', email).single();
-                if (result.error)
-                    return txt(`Error looking up contact: ${result.error.message}`);
-                existingContact = result.data;
+        try {
+            email = email.trim().toLowerCase();
+            const projectId = getProjectId();
+            // Block distribution list / system addresses
+            const DISTRO_LOCAL_PARTS = new Set(['all', 'everyone', 'distro', 'broadcast', 'announce', 'postmaster', 'abuse', 'mailer-daemon', 'bounce', 'bounces', 'noreply', 'no-reply', 'nobody', 'null', 'void']);
+            const DISTRO_PATTERNS = [/^all[-+.]/, /[-+.]all$/, /^list[-+.]/, /[-+.]list$/, /[-+.]announce$/, /^announce[-+.]/, /[-+.]distro$/, /^distro[-+.]/, /[-+.]broadcast$/, /^broadcast[-+.]/];
+            const local = email.trim().toLowerCase().split('@')[0] ?? '';
+            if (DISTRO_LOCAL_PARTS.has(local) || DISTRO_PATTERNS.some(p => p.test(local))) {
+                return contactInputError('validation_failed', `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.`);
             }
-        }
-        const existing = !!existingContact;
-        if (existingContact) {
-            const empty = (value) => value == null || value === '';
-            const row = {};
-            for (const [key, value] of Object.entries({ first_name, last_name, company_id: resolvedCompanyId })) {
-                if (empty(existingContact[key]) && !empty(value))
-                    row[key] = value;
+            // Validate project ownership before the cap, and reuse the double opt-in lookup.
+            const { data: siteInfo, error: siteError } = await db().from('sites')
+                .select('double_opt_in').eq('id', site_id).eq('project_id', projectId).maybeSingle();
+            if (siteError)
+                return dbErrorResult(siteError);
+            if (!siteInfo)
+                return contactInputError('not_found', 'Site not found for this project.');
+            const needsConfirm = siteInfo.double_opt_in === true;
+            const limit = await checkPlanLimit('contacts');
+            if (!limit.allowed) {
+                return contactInputError('plan_limit', contactLimitMessage(limit));
             }
-            if (!needsConfirm && existingContact.opted_in_at == null)
-                row.opted_in_at = new Date().toISOString();
-            const missingProperties = Object.fromEntries(Object.entries(customProperties ?? {})
-                .filter(([key]) => !Object.hasOwn(existingContact.custom_properties ?? {}, key)));
-            if (Object.keys(missingProperties).length) {
-                row.custom_properties = { ...(existingContact.custom_properties ?? {}), ...missingProperties };
+            const embedOk = await hasCompaniesEmbed(projectId);
+            const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
+            let { data: existingContact, error: lookupError } = await db()
+                .from('subscribers')
+                .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
+                .eq('project_id', projectId)
+                .eq('email', email)
+                .maybeSingle();
+            if (lookupError)
+                return dbErrorResult(lookupError);
+            let customProperties;
+            if (company_name || company_domain) {
+                const orgId = await getProjectOrgId(projectId);
+                customProperties = await normalizeMcpContactPropertyPatch({
+                    ...(company_name ? { company_name } : {}),
+                    ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
+                }, { orgId, projectId });
             }
-            if (Object.keys(row).length) {
-                let update = db().from('subscribers').update(row)
-                    .eq('id', existingContact.id).eq('project_id', projectId);
-                // The stored values must still match: a concurrent edit always wins over a re-add.
-                for (const key of Object.keys(row)) {
-                    const previous = existingContact[key];
-                    update = previous == null ? update.is(key, null)
-                        : update.eq(key, key === 'custom_properties' ? JSON.stringify(previous) : previous);
-                }
-                const { error } = await update;
+            const selection = embedOk ? '*, company:companies(id, name, domain)' : '*';
+            let contact;
+            if (!existingContact) {
+                const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
+                if (customProperties)
+                    row.custom_properties = customProperties;
+                if (!needsConfirm)
+                    row.opted_in_at = new Date().toISOString();
+                if (utm_source)
+                    row.utm_source = utm_source;
+                if (utm_medium)
+                    row.utm_medium = utm_medium;
+                if (utm_campaign)
+                    row.utm_campaign = utm_campaign;
+                if (utm_content)
+                    row.utm_content = utm_content;
+                if (utm_term)
+                    row.utm_term = utm_term;
+                const { data, error } = await db().from('subscribers')
+                    .upsert(row, { onConflict: 'project_id,email', ignoreDuplicates: true })
+                    .select(selection).maybeSingle();
                 if (error)
-                    return txt(`Error updating contact: ${error.message}`);
+                    return dbErrorResult(error);
+                contact = data;
+                if (!contact) {
+                    // A concurrent add won the unique key; its provenance belongs to that insert.
+                    const result = await db().from('subscribers')
+                        .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
+                        .eq('project_id', projectId).eq('email', email).single();
+                    if (result.error)
+                        return dbErrorResult(result.error);
+                    existingContact = result.data;
+                }
+            }
+            const existing = !!existingContact;
+            if (existingContact) {
+                const empty = (value) => value == null || value === '';
+                const row = {};
+                for (const [key, value] of Object.entries({ first_name, last_name, company_id: resolvedCompanyId })) {
+                    if (empty(existingContact[key]) && !empty(value))
+                        row[key] = value;
+                }
+                if (!needsConfirm && existingContact.opted_in_at == null)
+                    row.opted_in_at = new Date().toISOString();
+                const missingProperties = Object.fromEntries(Object.entries(customProperties ?? {})
+                    .filter(([key]) => !Object.hasOwn(existingContact.custom_properties ?? {}, key)));
+                if (Object.keys(missingProperties).length) {
+                    row.custom_properties = { ...(existingContact.custom_properties ?? {}), ...missingProperties };
+                }
+                if (Object.keys(row).length) {
+                    let update = db().from('subscribers').update(row)
+                        .eq('id', existingContact.id).eq('project_id', projectId);
+                    // The stored values must still match: a concurrent edit always wins over a re-add.
+                    for (const key of Object.keys(row)) {
+                        const previous = existingContact[key];
+                        update = previous == null ? update.is(key, null)
+                            : update.eq(key, key === 'custom_properties' ? JSON.stringify(previous) : previous);
+                    }
+                    const { error } = await update;
+                    if (error)
+                        return dbErrorResult(error);
+                }
+                const result = await db().from('subscribers').select(selection)
+                    .eq('id', existingContact.id).eq('project_id', projectId).single();
+                if (result.error)
+                    return dbErrorResult(result.error);
+                contact = result.data;
+            }
+            const existingMessage = existing ? { message: 'Contact already existed; source and existing fields were not changed.' } : {};
+            const { error: subErr } = await db()
+                .from('site_subscriptions')
+                .upsert({ contact_id: contact.id, site_id, subscribed: !needsConfirm }, { onConflict: 'contact_id,site_id' });
+            if (subErr)
+                return dbErrorResult(subErr);
+            if (existing)
+                logAudit({ action: 'contact.readded', resourceType: 'contact', resourceId: contact.id, details: { email, requested_source: source, existing: true } });
+            if (needsConfirm) {
+                // Create opt-in token (confirmation email must be sent externally in MCP context)
+                await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
+                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
+                logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
+                return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
             }
-            const result = await db().from('subscribers').select(selection)
-                .eq('id', existingContact.id).eq('project_id', projectId).single();
-            if (result.error)
-                return txt(`Error reading contact: ${result.error.message}`);
-            contact = result.data;
-        }
-        const existingMessage = existing ? { message: 'Contact already existed; source and existing fields were not changed.' } : {};
-        const { error: subErr } = await db()
-            .from('site_subscriptions')
-            .upsert({ contact_id: contact.id, site_id, subscribed: !needsConfirm }, { onConflict: 'contact_id,site_id' });
-        if (subErr)
-            return { content: [{ type: 'text', text: `Contact created but subscription failed: ${subErr.message}` }] };
-        if (existing)
-            logAudit({ action: 'contact.readded', resourceType: 'contact', resourceId: contact.id, details: { email, requested_source: source, existing: true } });
-        if (needsConfirm) {
-            // Create opt-in token (confirmation email must be sent externally in MCP context)
-            await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
             await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
-            logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
-            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
-        }
-        await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
-        logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
-        if (!existing)
-            logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
-        return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
+            logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
+            if (!existing)
+                logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
+            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
+        }
+        catch (error) {
+            return dbErrorResult(error);
+        }
     });
     server.registerTool('import_subscribers', {
         title: 'Import Subscribers',
@@ -1719,194 +1725,199 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             timezone: z.string().nullable().optional().describe('IANA time zone identifier, e.g. America/Los_Angeles'),
         },
     }, async ({ contact_id, email, first_name, last_name, company_id, company_name, company_domain, tags, custom_properties, phone_e164, timezone }) => {
-        const projectId = getProjectId();
-        let propertyWarnings = [];
-        let fields;
-        if (custom_properties !== undefined) {
-            let definitions;
-            try {
-                definitions = await registeredCustomFields(projectId);
-            }
-            catch {
-                return j({ error: 'Custom field definitions unavailable; update not performed', code: 'INTERNAL_ERROR' });
-            }
-            fields = Object.fromEntries(definitions.map(field => [field.key, field]));
-            const values = Object.fromEntries(Object.entries(custom_properties).filter(([, value]) => value !== null));
-            const invalidShape = Object.entries(values).find(([key, value]) => {
-                if (!Object.hasOwn(fields, key))
-                    return false;
-                const type = fields[key].type;
-                if (type === 'multi_select')
-                    return typeof value !== 'string' && (!Array.isArray(value) || value.some(item => typeof item !== 'string'));
-                return typeof value === 'object' && type !== 'contact_reference';
-            });
-            const { anomalies } = normalizeContactProperties(values, { fields });
-            if (invalidShape || anomalies.length) {
-                const key = invalidShape?.[0] ?? anomalies[0].key;
-                return contactInputError('validation_failed', `custom_properties.${key} does not match its registered ${fields[key].type} definition or options`);
-            }
-            propertyWarnings = unknownCustomPropertyWarnings(custom_properties, fields);
-        }
-        const embedOk = await hasCompaniesEmbed(projectId);
-        const updates = {};
-        let customPropertyChanges = [];
-        if (email !== undefined)
-            updates.email = email;
-        if (first_name !== undefined)
-            updates.first_name = first_name;
-        if (last_name !== undefined)
-            updates.last_name = last_name;
-        if (company_id !== undefined) {
-            updates.company_id = company_id;
-        }
-        else if (company_name || company_domain) {
-            updates.company_id = await resolveCompanyId(projectId, {
-                company_name: company_name ?? undefined,
-                company_domain: company_domain ?? undefined,
-            });
-        }
-        if (tags !== undefined)
-            updates.tags = tags;
-        if (custom_properties !== undefined) {
-            const { data: existing, error: existingError } = await db()
-                .from('subscribers')
-                .select('custom_properties')
-                .eq('id', contact_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            if (existingError)
-                return j({ error: 'Contact properties unavailable; update not performed', code: 'INTERNAL_ERROR' });
-            if (!existing)
-                return contactInputError('not_found', 'Contact not found');
-            const orgId = await getProjectOrgId(projectId);
-            const normalizedPatch = await normalizeMcpContactPropertyPatch(custom_properties, {
-                orgId,
-                projectId,
-                subscriberId: contact_id,
-                preserveNullDeletions: true,
-                fields,
-            });
-            customPropertyChanges = diffCustomProperties(existing?.custom_properties ?? null, normalizedPatch);
-            updates.custom_properties = {
-                ...(existing?.custom_properties ?? {}),
-                ...normalizedPatch,
-                ...(company_name ? { company_name } : {}),
-                ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
-            };
-            for (const [key, value] of Object.entries(normalizedPatch)) {
-                if (value === null)
-                    delete updates.custom_properties[key];
-            }
-        }
-        else if (company_name || company_domain) {
-            const { data: existing } = await db()
-                .from('subscribers')
-                .select('custom_properties')
-                .eq('id', contact_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            const orgId = await getProjectOrgId(projectId);
-            const companyPatch = await normalizeMcpContactPropertyPatch({
-                ...(company_name ? { company_name } : {}),
-                ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
-            }, { orgId, projectId, subscriberId: contact_id });
-            updates.custom_properties = {
-                ...(existing?.custom_properties ?? {}),
-                ...companyPatch,
-            };
-        }
-        if (phone_e164 !== undefined) {
-            if (phone_e164 === null) {
-                updates.phone_e164 = null;
-            }
-            else {
-                const normalized = normalizePhoneE164(phone_e164);
-                if (!normalized)
-                    return contactInputError('validation_failed', 'Invalid phone_e164: must be a valid E.164 phone number (SMS is US-only for now).');
-                updates.phone_e164 = normalized;
-            }
-        }
-        if (timezone !== undefined) {
-            if (timezone === null) {
-                updates.timezone = null;
-            }
-            else {
-                // Region form only; mirrors normalizeTimezoneField in the dashboard. Intl accepts UTC offsets
-                // ("+05:00") and abbreviations ("EST"), which Postgres AT TIME ZONE reads differently.
-                if (timezone !== 'UTC' && !/^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)+$/.test(timezone)) {
-                    return contactInputError('validation_failed', 'Invalid timezone: must be an IANA region name such as America/Los_Angeles (not a UTC offset or abbreviation).');
-                }
+        try {
+            const projectId = getProjectId();
+            let propertyWarnings = [];
+            let fields;
+            if (custom_properties !== undefined) {
+                let definitions;
                 try {
-                    new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+                    definitions = await registeredCustomFields(projectId);
                 }
                 catch {
-                    return contactInputError('validation_failed', 'Invalid timezone: must be a valid IANA time zone identifier.');
+                    return j({ error: 'Custom field definitions unavailable; update not performed', code: 'INTERNAL_ERROR' });
                 }
-                updates.timezone = timezone;
+                fields = Object.fromEntries(definitions.map(field => [field.key, field]));
+                const values = Object.fromEntries(Object.entries(custom_properties).filter(([, value]) => value !== null));
+                const invalidShape = Object.entries(values).find(([key, value]) => {
+                    if (!Object.hasOwn(fields, key))
+                        return false;
+                    const type = fields[key].type;
+                    if (type === 'multi_select')
+                        return typeof value !== 'string' && (!Array.isArray(value) || value.some(item => typeof item !== 'string'));
+                    return typeof value === 'object' && type !== 'contact_reference';
+                });
+                const { anomalies } = normalizeContactProperties(values, { fields });
+                if (invalidShape || anomalies.length) {
+                    const key = invalidShape?.[0] ?? anomalies[0].key;
+                    return contactInputError('validation_failed', `custom_properties.${key} does not match its registered ${fields[key].type} definition or options`);
+                }
+                propertyWarnings = unknownCustomPropertyWarnings(custom_properties, fields);
             }
-        }
-        if (!Object.keys(updates).length)
-            return contactInputError('validation_failed', 'No fields to update.');
-        const tagResult = {};
-        if (tags !== undefined) {
-            let previousTags;
-            try {
-                const { data: existing, error: readError } = await db()
+            const embedOk = await hasCompaniesEmbed(projectId);
+            const updates = {};
+            let customPropertyChanges = [];
+            if (email !== undefined)
+                updates.email = email;
+            if (first_name !== undefined)
+                updates.first_name = first_name;
+            if (last_name !== undefined)
+                updates.last_name = last_name;
+            if (company_id !== undefined) {
+                updates.company_id = company_id;
+            }
+            else if (company_name || company_domain) {
+                updates.company_id = await resolveCompanyId(projectId, {
+                    company_name: company_name ?? undefined,
+                    company_domain: company_domain ?? undefined,
+                });
+            }
+            if (tags !== undefined)
+                updates.tags = tags;
+            if (custom_properties !== undefined) {
+                const { data: existing, error: existingError } = await db()
                     .from('subscribers')
-                    .select('tags')
+                    .select('custom_properties')
                     .eq('id', contact_id)
                     .eq('project_id', projectId)
                     .maybeSingle();
-                if (!readError && Array.isArray(existing?.tags) && existing.tags.every((tag) => typeof tag === 'string')) {
-                    previousTags = existing.tags;
+                if (existingError)
+                    return j({ error: 'Contact properties unavailable; update not performed', code: 'INTERNAL_ERROR' });
+                if (!existing)
+                    return contactInputError('not_found', 'Contact not found');
+                const orgId = await getProjectOrgId(projectId);
+                const normalizedPatch = await normalizeMcpContactPropertyPatch(custom_properties, {
+                    orgId,
+                    projectId,
+                    subscriberId: contact_id,
+                    preserveNullDeletions: true,
+                    fields,
+                });
+                customPropertyChanges = diffCustomProperties(existing?.custom_properties ?? null, normalizedPatch);
+                updates.custom_properties = {
+                    ...(existing?.custom_properties ?? {}),
+                    ...normalizedPatch,
+                    ...(company_name ? { company_name } : {}),
+                    ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
+                };
+                for (const [key, value] of Object.entries(normalizedPatch)) {
+                    if (value === null)
+                        delete updates.custom_properties[key];
                 }
             }
-            catch {
-                // The replacement can still succeed, but the previous set is unknown.
+            else if (company_name || company_domain) {
+                const { data: existing } = await db()
+                    .from('subscribers')
+                    .select('custom_properties')
+                    .eq('id', contact_id)
+                    .eq('project_id', projectId)
+                    .maybeSingle();
+                const orgId = await getProjectOrgId(projectId);
+                const companyPatch = await normalizeMcpContactPropertyPatch({
+                    ...(company_name ? { company_name } : {}),
+                    ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
+                }, { orgId, projectId, subscriberId: contact_id });
+                updates.custom_properties = {
+                    ...(existing?.custom_properties ?? {}),
+                    ...companyPatch,
+                };
             }
-            if (previousTags === undefined) {
-                tagResult.warnings = ['Tags were REPLACED, but previous tags could not be read; removed and added tags are unknown. Use set_subscriber_tags to add tags without replacing the whole set.'];
+            if (phone_e164 !== undefined) {
+                if (phone_e164 === null) {
+                    updates.phone_e164 = null;
+                }
+                else {
+                    const normalized = normalizePhoneE164(phone_e164);
+                    if (!normalized)
+                        return contactInputError('validation_failed', 'Invalid phone_e164: must be a valid E.164 phone number (SMS is US-only for now).');
+                    updates.phone_e164 = normalized;
+                }
             }
-            else {
-                const previousSet = new Set(previousTags);
-                const nextSet = new Set(tags);
-                tagResult.tags_removed = [...previousSet].filter((tag) => !nextSet.has(tag));
-                tagResult.tags_added = [...nextSet].filter((tag) => !previousSet.has(tag));
-                if (tagResult.tags_removed.length > 0) {
-                    tagResult.warnings = ['Tags were REPLACED. Use set_subscriber_tags to add tags without replacing the whole set.'];
+            if (timezone !== undefined) {
+                if (timezone === null) {
+                    updates.timezone = null;
+                }
+                else {
+                    // Region form only; mirrors normalizeTimezoneField in the dashboard. Intl accepts UTC offsets
+                    // ("+05:00") and abbreviations ("EST"), which Postgres AT TIME ZONE reads differently.
+                    if (timezone !== 'UTC' && !/^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)+$/.test(timezone)) {
+                        return contactInputError('validation_failed', 'Invalid timezone: must be an IANA region name such as America/Los_Angeles (not a UTC offset or abbreviation).');
+                    }
+                    try {
+                        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+                    }
+                    catch {
+                        return contactInputError('validation_failed', 'Invalid timezone: must be a valid IANA time zone identifier.');
+                    }
+                    updates.timezone = timezone;
                 }
             }
-        }
-        updates.updated_at = new Date().toISOString();
-        const { data, error } = await db()
-            .from('subscribers')
-            .update(updates)
-            .eq('id', contact_id)
-            .eq('project_id', projectId)
-            .select(embedOk ? UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY : UPDATE_SUBSCRIBER_SELECT_NO_COMPANY)
-            .single();
-        if (error?.code === '23505' && updates.phone_e164 !== undefined) {
-            return contactInputError('conflict', 'Another contact in this project already has this phone number.');
-        }
-        if (error)
-            return j({ error: `Error: ${error.message}`, code: 'INTERNAL_ERROR' });
-        if (customPropertyChanges.length > 0) {
-            logAudit({
-                action: 'contact.custom_properties_changed',
-                resourceType: 'contact',
-                resourceId: contact_id,
-                details: { changes: customPropertyChanges },
+            if (!Object.keys(updates).length)
+                return contactInputError('validation_failed', 'No fields to update.');
+            const tagResult = {};
+            if (tags !== undefined) {
+                let previousTags;
+                try {
+                    const { data: existing, error: readError } = await db()
+                        .from('subscribers')
+                        .select('tags')
+                        .eq('id', contact_id)
+                        .eq('project_id', projectId)
+                        .maybeSingle();
+                    if (!readError && Array.isArray(existing?.tags) && existing.tags.every((tag) => typeof tag === 'string')) {
+                        previousTags = existing.tags;
+                    }
+                }
+                catch {
+                    // The replacement can still succeed, but the previous set is unknown.
+                }
+                if (previousTags === undefined) {
+                    tagResult.warnings = ['Tags were REPLACED, but previous tags could not be read; removed and added tags are unknown. Use set_subscriber_tags to add tags without replacing the whole set.'];
+                }
+                else {
+                    const previousSet = new Set(previousTags);
+                    const nextSet = new Set(tags);
+                    tagResult.tags_removed = [...previousSet].filter((tag) => !nextSet.has(tag));
+                    tagResult.tags_added = [...nextSet].filter((tag) => !previousSet.has(tag));
+                    if (tagResult.tags_removed.length > 0) {
+                        tagResult.warnings = ['Tags were REPLACED. Use set_subscriber_tags to add tags without replacing the whole set.'];
+                    }
+                }
+            }
+            updates.updated_at = new Date().toISOString();
+            const { data, error } = await db()
+                .from('subscribers')
+                .update(updates)
+                .eq('id', contact_id)
+                .eq('project_id', projectId)
+                .select(embedOk ? UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY : UPDATE_SUBSCRIBER_SELECT_NO_COMPANY)
+                .single();
+            if (error?.code === '23505' && updates.phone_e164 !== undefined) {
+                return contactInputError('conflict', 'Another contact in this project already has this phone number.');
+            }
+            if (error)
+                return dbErrorResult(error);
+            if (customPropertyChanges.length > 0) {
+                logAudit({
+                    action: 'contact.custom_properties_changed',
+                    resourceType: 'contact',
+                    resourceId: contact_id,
+                    details: { changes: customPropertyChanges },
+                });
+            }
+            await writeBackMcpContact(projectId, data, {
+                ...(updates.email !== undefined ? { email: updates.email } : {}),
+                ...(updates.first_name !== undefined ? { first_name: updates.first_name } : {}),
+                ...(updates.last_name !== undefined ? { last_name: updates.last_name } : {}),
+                ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
+                ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
             });
+            const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings];
+            return j({ ...data, ...tagResult, ...(mergedWarnings.length ? { warnings: mergedWarnings } : {}) });
+        }
+        catch (error) {
+            return dbErrorResult(error);
         }
-        await writeBackMcpContact(projectId, data, {
-            ...(updates.email !== undefined ? { email: updates.email } : {}),
-            ...(updates.first_name !== undefined ? { first_name: updates.first_name } : {}),
-            ...(updates.last_name !== undefined ? { last_name: updates.last_name } : {}),
-            ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
-            ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
-        });
-        const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings];
-        return j({ ...data, ...tagResult, ...(mergedWarnings.length ? { warnings: mergedWarnings } : {}) });
     });
     server.registerTool('get_subscriber', {
         title: 'Get Subscriber',

package/build/tools/segments.js

@@ -1,3 +1,4 @@
+import { dbErrorResult } from '../lib/db-errors.js';
 import { withApproval } from '../lib/action-approvals.js';
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
@@ -80,31 +81,36 @@ 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>, email_sends (eq only, value: {min_count: positive integer, within_days: positive number}; at most one per segment). 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);
+            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: storedRules })
+                .select('id, name, description, rules, created_at')
+                .single();
+            if (error)
+                return dbErrorResult(error);
+            // Count against the stored (normalized) tree, not the raw input: a tree skips
+            // applySegmentRules' SQL push-down and filters in JS, which is what list_segments
+            // does for this same segment a moment later. Pushing the flat rules down instead
+            // makes the two disagree wherever SQL and JS compare differently -- notably
+            // custom_property against a non-string JSONB value (boolean/number), where
+            // `@> {"k":"true"}` misses a stored `true` but String(actual)===String(expected) matches.
+            const ids = await getSegmentContactIds(data.rules);
+            return j({ ...data, estimated_contacts: ids.length });
         }
-        catch (rulesError) {
-            const invalid = invalidRules(rulesError);
-            if (invalid)
-                return invalid;
-            throw rulesError;
+        catch (error) {
+            return dbErrorResult(error);
         }
-        const { data, error } = await db()
-            .from('segments')
-            .insert({ project_id: getProjectId(), name, description, rules: storedRules })
-            .select('id, name, description, rules, created_at')
-            .single();
-        if (error)
-            return txt(`Error: ${error.message}`);
-        // Count against the stored (normalized) tree, not the raw input: a tree skips
-        // applySegmentRules' SQL push-down and filters in JS, which is what list_segments
-        // does for this same segment a moment later. Pushing the flat rules down instead
-        // makes the two disagree wherever SQL and JS compare differently -- notably
-        // custom_property against a non-string JSONB value (boolean/number), where
-        // `@> {"k":"true"}` misses a stored `true` but String(actual)===String(expected) matches.
-        const ids = await getSegmentContactIds(data.rules);
-        return j({ ...data, estimated_contacts: ids.length });
     });
     server.registerTool('list_segments', {
         title: 'List Segments',
@@ -157,32 +163,37 @@ export function registerSegmentTools(server) {
             rules: z.record(z.string(), z.unknown()).optional(),
         },
     }, async ({ segment_id, name, description, rules }) => {
-        const updates = { updated_at: new Date().toISOString() };
-        if (name)
-            updates.name = name;
-        if (description !== undefined)
-            updates.description = description;
-        if (rules) {
-            try {
-                updates.rules = prepareSegmentRulesForStorage(rules);
-            }
-            catch (rulesError) {
-                const invalid = invalidRules(rulesError);
-                if (invalid)
-                    return invalid;
-                throw rulesError;
+        try {
+            const updates = { updated_at: new Date().toISOString() };
+            if (name)
+                updates.name = name;
+            if (description !== undefined)
+                updates.description = description;
+            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)
+                .eq('id', segment_id)
+                .eq('project_id', getProjectId())
+                .select('id, name, description, rules, updated_at')
+                .single();
+            if (error)
+                return dbErrorResult(error);
+            return j(data);
+        }
+        catch (error) {
+            return dbErrorResult(error);
         }
-        const { data, error } = await db()
-            .from('segments')
-            .update(updates)
-            .eq('id', segment_id)
-            .eq('project_id', getProjectId())
-            .select('id, name, description, rules, updated_at')
-            .single();
-        if (error)
-            return txt(`Error: ${error.message}`);
-        return j(data);
     });
     server.registerTool('delete_segment', {
         title: 'Delete Segment',

package/package.json

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