@sendinel/mcp-server 1.0.138 → 1.0.140

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';
@@ -24,6 +25,40 @@ const CUSTOM_FIELD_TYPES = [
     'multi_select', 'contact_reference',
 ];
 const CUSTOM_FIELD_KEY_RE = /^[a-z][a-z0-9_]{0,49}$/;
+// Core contact columns from 001_core_schema.sql and subsequent subscriber migrations.
+const RESERVED_CUSTOM_FIELD_KEYS = new Set([
+    'email', 'first_name', 'last_name', 'id', 'phone', 'status', 'tags', 'project_id', 'org_id', 'user_id',
+    'created_at', 'updated_at', 'clerk_user_id', 'global_unsubscribed', 'global_unsubscribed_at',
+    'source', 'source_site', 'ip_address', 'opted_in_at', 'last_emailed_at', 'last_opened_at',
+    'last_clicked_at', 'total_emails_sent', 'total_opens', 'total_clicks', 'engagement_score',
+    'lifecycle_stage', 'score_updated_at', 'custom_properties', 'timezone', 'last_engaged_at',
+    'utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term', 'best_send_hour',
+    'best_send_hour_confidence', 'best_send_hour_updated_at', 'notes', 'birthday', 'anniversary',
+    'external_id', 'imported_from', 'phone_e164', 'sms_opt_in_status', 'sms_opt_in_at',
+    'sms_opt_out_at', 'is_test', 'company_id', 'source_deleted_at', 'cooled_at', 'cooled_reason',
+    'introduced_by_subscriber_id', 'ccpa_opted_out', 'last_transactional_at',
+    'total_transactional_sent', 'last_activity_at',
+]);
+const CUSTOM_FIELD_COLUMNS = 'id, key, label, type, required, options, display_order';
+async function registeredCustomFields(projectId) {
+    return readAllRows(db().from('custom_field_definitions').select(CUSTOM_FIELD_COLUMNS).eq('project_id', projectId));
+}
+function keyDistance(left, right) {
+    let row = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 0; i < left.length; i++) {
+        const next = [i + 1];
+        for (let j = 0; j < right.length; j++)
+            next.push(Math.min(next[j] + 1, row[j + 1] + 1, row[j] + (left[i] === right[j] ? 0 : 1)));
+        row = next;
+    }
+    return row[right.length];
+}
+function unknownCustomPropertyWarnings(patch, fields) {
+    return Object.keys(patch).filter(key => !Object.hasOwn(fields, key)).map(key => {
+        const near = Object.keys(fields).filter(known => keyDistance(key, known) <= 2);
+        return `Unknown custom property "${key}"${near.length ? `; did you mean ${near.map(value => `"${value}"`).join(' or ')}?` : '; no registered definition'}`;
+    });
+}
 const SUBSCRIBER_VIEW_MAX_NAME_LENGTH = 100;
 const SUBSCRIBER_VIEW_MAX_COLUMNS = 150;
 const SUBSCRIBER_VIEW_KEY_RE = /^[a-zA-Z0-9_.:-]{1,160}$/;
@@ -1219,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',
@@ -1670,7 +1710,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Update a contact\'s email, name, phone, timezone, tags, or custom properties. tags replaces the whole tag set; use set_subscriber_tags to add tags.',
+        description: 'Update a contact\'s email, name, phone, timezone, tags, or custom properties. tags replaces the whole tag set; use set_subscriber_tags to add tags. Registered custom properties must match their type/options; unknown keys remain allowed with warnings and near-miss suggestions.',
         inputSchema: {
             contact_id: z.string().uuid(),
             email: z.string().email().optional(),
@@ -1685,161 +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();
-        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 } = await db()
-                .from('subscribers')
-                .select('custom_properties')
-                .eq('id', contact_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            const orgId = await getProjectOrgId(projectId);
-            const normalizedPatch = await normalizeMcpContactPropertyPatch(custom_properties, {
-                orgId,
-                projectId,
-                subscriberId: contact_id,
-                preserveNullDeletions: true,
-            });
-            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 txt('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('validation_failed', 'Another contact in this project already has this phone number.');
-        }
-        if (error)
-            return txt(`Error: ${error.message}`);
-        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 } : {}),
-        });
-        return j({ ...data, ...tagResult });
     });
     server.registerTool('get_subscriber', {
         title: 'Get Subscriber',
@@ -2515,7 +2593,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Discover all custom_properties keys used across contacts for a site. Returns the list of keys, example values, and merge tag syntax so you can use them in campaigns. Call this before generating emails to know what personalisation data is available.',
+        description: 'Discover registered custom field definitions and all custom_properties keys used across contacts for a site, including unused definitions. Returns the list of keys, example values, and merge tag syntax so you can use them in campaigns. Call this before generating emails to know what personalisation data is available.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site to inspect — only contacts belonging to this site are sampled'),
         },
@@ -2539,20 +2617,34 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         // site-scoped; project scope is only for a site with no members at all.
         let loaded = await loadSchemaKeys(site_id);
         if ('error' in loaded)
-            return txt(loaded.error);
+            return j({ error: loaded.error, code: 'INTERNAL_ERROR' });
         let scope = 'site';
         if (!loaded.has_membership) {
             loaded = await loadSchemaKeys(null);
             if ('error' in loaded)
-                return txt(loaded.error);
+                return j({ error: loaded.error, code: 'INTERNAL_ERROR' });
             scope = 'project';
         }
-        const schema = loaded.keys.map(({ key, contacts_with_this_key, example_values }) => ({
+        let definitions;
+        try {
+            definitions = await registeredCustomFields(projectId);
+        }
+        catch {
+            return j({ error: 'Custom field definitions unavailable', code: 'INTERNAL_ERROR' });
+        }
+        const byKey = new Map(definitions.map(field => [field.key, field]));
+        const keys = [...loaded.keys];
+        const observed = new Set(keys.map(row => row.key));
+        for (const field of definitions)
+            if (!observed.has(field.key))
+                keys.push({ key: field.key, contacts_with_this_key: 0, example_values: [] });
+        const schema = keys.map(({ key, contacts_with_this_key, example_values }) => ({
             key,
             merge_tag: `{{custom.${key}}}`,
             merge_tag_with_fallback: `{{custom.${key}|fallback}}`,
             example_values,
             contacts_with_this_key,
+            ...(byKey.has(key) ? { definition: byKey.get(key) } : {}),
         }));
         return j({
             site_id,
@@ -2564,6 +2656,20 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 : 'Use merge_tag syntax in email body/subject. For sensitive data, add a fallback: {{custom.plan|subscriber}}. ⚠️ custom_properties data passes through the Anthropic API — avoid storing sensitive PII (SSNs, passwords, financial account numbers).',
         });
     });
+    server.registerTool('list_custom_fields', {
+        title: 'List Custom Fields',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'List all registered custom field definitions for the current project, including fields with no contact values yet.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const fields = await registeredCustomFields(getProjectId());
+            return j({ fields, count: fields.length });
+        }
+        catch {
+            return j({ error: 'Custom field definitions unavailable', code: 'INTERNAL_ERROR' });
+        }
+    });
     server.registerTool('create_custom_field', {
         title: 'Create Custom Field',
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -2577,9 +2683,11 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             display_order: z.number().int().optional().default(0),
         },
     }, async ({ key, label, type, required, options, display_order }) => {
+        if (RESERVED_CUSTOM_FIELD_KEYS.has(key))
+            return contactInputError('validation_failed', `Custom field key "${key}" is reserved for a core contact column`);
         const optionsError = validateCustomFieldOptions(type, options);
         if (optionsError)
-            return txt(`Error: ${optionsError}`);
+            return contactInputError('validation_failed', `Error: ${optionsError}`);
         const normalizedOptions = type === 'select' || type === 'multi_select'
             ? normalizeCustomFieldOptions(options)
             : null;
@@ -2601,8 +2709,8 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .single();
         if (error) {
             if (error.code === '23505')
-                return txt(`Error: A custom field with key "${key}" already exists.`);
-            return txt(`Error: ${error.message}`);
+                return contactInputError('conflict', `Error: A custom field with key "${key}" already exists.`);
+            return j({ error: `Error: ${error.message}`, code: 'INTERNAL_ERROR' });
         }
         await logAudit({
             action: 'custom_field.created',