@sendinel/mcp-server 1.0.9 → 1.0.11

package/build/tools/contacts.js

@@ -1,5 +1,7 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
 import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
+import { buildPreviewAttentionEnvelope, applySegmentRules, ContactPropertyAnomalyLogger, normalizeContactProperties, getAttentionDecision, getContactNeighborhood, getScheduledTouches, } from '@sendinel/domain';
 import { z } from 'zod';
 import { db, projectClientForWriteback } from '../db.js';
 import { getProjectId } from '../project.js';
@@ -8,10 +10,61 @@ import { logConsent, logAudit } from '../audit.js';
 import { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval } from '../lib/action-approvals.js';
 import { decrypt } from '../crypto.js';
 import { normalizeActiveCampaignAccountUrl } from '../lib/url-validation.js';
+import { diffCustomProperties } from '../lib/custom-properties-diff.js';
 import Anthropic from '@anthropic-ai/sdk';
 import { getAnthropicModelId } from '../anthropic-model.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
+const CUSTOM_FIELD_TYPES = [
+    'email', 'text', 'textarea', 'select', 'checkbox', 'number', 'tel', 'url', 'date',
+    'multi_select', 'contact_reference',
+];
+const CUSTOM_FIELD_KEY_RE = /^[a-z][a-z0-9_]{0,49}$/;
+const SUBSCRIBER_VIEW_MAX_NAME_LENGTH = 100;
+const SUBSCRIBER_VIEW_MAX_COLUMNS = 150;
+const SUBSCRIBER_VIEW_KEY_RE = /^[a-zA-Z0-9_.:-]{1,160}$/;
+const SUBSCRIBER_VIEW_FILTER_KEYS = new Set([
+    'search',
+    'tag',
+    'stage',
+    'status',
+    'cp_key',
+    'cp_value',
+    'site',
+    'sort',
+    'dir',
+    'show_test',
+]);
+const SUBSCRIBER_VIEW_SORT_FIELDS = new Set([
+    'created_at',
+    'engagement_score',
+    'total_opens',
+    'total_clicks',
+    'last_emailed_at',
+    'lifecycle_stage',
+    'email',
+]);
+const SUBSCRIBER_VIEW_CUSTOM_PROPERTY_KEY_RE = /^[a-zA-Z0-9_.-]{1,64}$/;
+const SUBSCRIBER_VIEW_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const subscriberViewColumnsSchema = z.object({
+    order: z.array(z.string()).optional(),
+    hidden: z.array(z.string()).optional(),
+});
+function normalizeCustomFieldOptions(options) {
+    if (options === undefined)
+        return undefined;
+    if (options === null)
+        return null;
+    return options.map((option) => option.trim()).filter(Boolean);
+}
+function validateCustomFieldOptions(type, options) {
+    if (type !== 'select' && type !== 'multi_select')
+        return null;
+    if (!Array.isArray(options) || options.some((option) => typeof option !== 'string')) {
+        return `type "${type}" requires an options array of strings`;
+    }
+    return null;
+}
 async function byodWritebackClient(projectId) {
     const customer = projectClientForWriteback();
     if (!customer)
@@ -130,6 +183,145 @@ function normalizeCompanyDomain(value) {
 function normalizeEmail(value) {
     return String(value ?? '').trim().toLowerCase();
 }
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeSubscriberViewKeys(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value
+            .filter((key) => typeof key === 'string')
+            .map((key) => key.trim())
+            .filter((key) => SUBSCRIBER_VIEW_KEY_RE.test(key)))]
+        .slice(0, SUBSCRIBER_VIEW_MAX_COLUMNS);
+}
+function normalizeSubscriberViewColumns(value) {
+    const input = isPlainObject(value) ? value : {};
+    return {
+        order: normalizeSubscriberViewKeys(input.order),
+        hidden: normalizeSubscriberViewKeys(input.hidden),
+    };
+}
+function normalizeSubscriberViewFilters(value) {
+    if (!isPlainObject(value))
+        return {};
+    const output = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (!SUBSCRIBER_VIEW_FILTER_KEYS.has(key))
+            continue;
+        if (key === 'show_test') {
+            output[key] = raw === true;
+        }
+        else if (typeof raw === 'string') {
+            output[key] = raw.slice(0, 500);
+        }
+    }
+    if (output.dir !== 'asc' && output.dir !== 'desc')
+        delete output.dir;
+    return output;
+}
+function subscriberViewFilterString(filters, key) {
+    const value = filters[key];
+    return typeof value === 'string' ? value.trim() : '';
+}
+function subscriberViewCustomPropertyPath(key) {
+    const dot = key.indexOf('.');
+    if (dot === -1)
+        return `custom_properties->>'${key}'`;
+    return `custom_properties->'${key.slice(0, dot)}'->>'${key.slice(dot + 1)}'`;
+}
+async function resolveSubscriberViewSiteId(projectId, siteParam) {
+    const { data: sites, error } = await db()
+        .from('sites')
+        .select('id')
+        .eq('project_id', projectId)
+        .eq('active', true)
+        .order('name');
+    if (error)
+        return { error: error.message };
+    const all = (sites ?? []);
+    if (SUBSCRIBER_VIEW_UUID_RE.test(siteParam)) {
+        return { siteId: all.some((site) => site.id === siteParam) ? siteParam : undefined };
+    }
+    const displayId = Number(siteParam);
+    return {
+        siteId: Number.isInteger(displayId) && displayId > 0 ? all[displayId - 1]?.id : undefined,
+    };
+}
+async function getProjectOrgId(projectId) {
+    const { data } = await db().from('projects').select('org_id').eq('id', projectId).maybeSingle();
+    return typeof data?.org_id === 'string' && data.org_id ? data.org_id : projectId;
+}
+async function loadContactPropertyDefinitions(projectId) {
+    try {
+        const client = db();
+        const scoped = typeof client.schema === 'function' ? client.schema('email') : client;
+        const { data, error } = await scoped
+            .from('custom_field_definitions')
+            .select('key, type, options')
+            .eq('project_id', projectId);
+        if (error) {
+            console.warn('[contact-properties] MCP definition load failed:', error.message ?? error);
+            return {};
+        }
+        const fields = {};
+        for (const row of data ?? []) {
+            const key = typeof row.key === 'string' ? row.key : '';
+            const type = row.type;
+            if (!key || !type)
+                continue;
+            fields[key] = {
+                type,
+                options: Array.isArray(row.options) ? row.options : null,
+            };
+        }
+        return fields;
+    }
+    catch (error) {
+        console.warn('[contact-properties] MCP definition load threw:', error);
+        return {};
+    }
+}
+async function normalizeMcpContactPropertyPatch(raw, options) {
+    if (!raw)
+        return {};
+    const fields = options.fields ?? await loadContactPropertyDefinitions(options.projectId);
+    const knownScalarPatch = {};
+    const passthrough = {};
+    const nullDeletions = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === null && options.preserveNullDeletions) {
+            nullDeletions[key] = null;
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, key) && !isPlainObject(value)) {
+            knownScalarPatch[key] = value;
+        }
+        else {
+            passthrough[key] = value;
+        }
+    }
+    const { properties, anomalies } = normalizeContactProperties(knownScalarPatch, { fields });
+    if (anomalies.length > 0) {
+        const logger = options.anomalyLogger ?? new ContactPropertyAnomalyLogger({
+            orgId: options.orgId,
+            projectId: options.projectId,
+            subscriberId: options.subscriberId ?? null,
+            pipeline: 'mcp_subscriber_tools',
+        });
+        if (options.subscriberId !== undefined)
+            logger.setSubscriberId(options.subscriberId);
+        for (const anomaly of anomalies)
+            logger.log(anomaly.key, anomaly.rawValue, anomaly.reason);
+        if (!options.anomalyLogger)
+            await logger.flush(db());
+    }
+    return {
+        ...passthrough,
+        ...properties,
+        ...nullDeletions,
+    };
+}
 const companiesEmbedCache = new Map();
 function isMissingRelationshipError(error) {
     if (!error)
@@ -588,28 +780,73 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List contacts, optionally filtered by site and/or search term',
+        description: 'List contacts, optionally filtered by site, search term, and/or a saved subscriber view. Explicit arguments and saved-view filters are combined to narrow the result.',
         inputSchema: {
             site_id: z.string().uuid().optional(),
             company_id: z.string().uuid().optional(),
             company_domain: z.string().optional(),
             search: z.string().optional().describe('Partial match on email, first_name, or last_name'),
+            view_id: z.string().uuid().optional().describe('Saved subscriber view whose filters should also be applied'),
             limit: z.number().int().min(1).max(200).optional().default(50),
             include_unsubscribed: z.boolean().optional().default(false),
         },
-    }, async ({ site_id, company_id, company_domain, search, limit, include_unsubscribed }) => {
+    }, async ({ site_id, company_id, company_domain, search, view_id, limit, include_unsubscribed }) => {
         const projectId = getProjectId();
+        let viewFilters = null;
+        if (view_id) {
+            const { data: view, error: viewError } = await db()
+                .from('subscriber_list_views')
+                .select('filters')
+                .eq('id', view_id)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (viewError)
+                return txt(`Error: ${viewError.message}`);
+            if (!view)
+                return txt('Error: View not found');
+            viewFilters = normalizeSubscriberViewFilters(view.filters);
+        }
+        const viewSearch = viewFilters ? subscriberViewFilterString(viewFilters, 'search') : '';
+        const viewStage = viewFilters ? subscriberViewFilterString(viewFilters, 'stage') : '';
+        const viewCustomPropertyKey = viewFilters ? subscriberViewFilterString(viewFilters, 'cp_key') : '';
+        const viewCustomPropertyValue = viewFilters ? subscriberViewFilterString(viewFilters, 'cp_value') : '';
+        const viewSiteParam = viewFilters ? subscriberViewFilterString(viewFilters, 'site') : '';
+        const viewStatus = viewFilters ? subscriberViewFilterString(viewFilters, 'status') : '';
+        const viewSort = viewFilters ? subscriberViewFilterString(viewFilters, 'sort') : '';
+        const viewDir = viewFilters ? subscriberViewFilterString(viewFilters, 'dir') : '';
+        const viewTags = viewFilters
+            ? [...new Set(subscriberViewFilterString(viewFilters, 'tag').split(',').map((tag) => tag.trim()).filter(Boolean))].slice(0, 20)
+            : [];
+        let viewSiteId;
+        if (viewSiteParam && viewSiteParam !== 'all') {
+            const resolved = await resolveSubscriberViewSiteId(projectId, viewSiteParam);
+            if (resolved.error)
+                return txt(`Error: ${resolved.error}`);
+            viewSiteId = resolved.siteId;
+        }
         const embedOk = await hasCompaniesEmbed(projectId);
+        const sortField = SUBSCRIBER_VIEW_SORT_FIELDS.has(viewSort) ? viewSort : 'created_at';
         let q = db()
             .from('subscribers')
             .select(embedOk ? SUBSCRIBER_SELECT_WITH_COMPANY : SUBSCRIBER_SELECT_NO_COMPANY)
             .eq('project_id', projectId)
-            .order('created_at', { ascending: false })
+            .order(sortField, { ascending: viewFilters !== null && viewDir === 'asc' })
             .limit(limit ?? 50);
         if (!include_unsubscribed)
             q = q.eq('global_unsubscribed', false);
         if (search)
             q = q.or(`email.ilike.%${search}%,first_name.ilike.%${search}%,last_name.ilike.%${search}%`);
+        if (viewSearch)
+            q = q.or(`email.ilike.%${viewSearch}%,first_name.ilike.%${viewSearch}%,last_name.ilike.%${viewSearch}%`);
+        if (viewTags.length > 0)
+            q = q.contains('tags', viewTags);
+        if (viewStage)
+            q = q.eq('lifecycle_stage', viewStage);
+        if (viewCustomPropertyKey && viewCustomPropertyValue && SUBSCRIBER_VIEW_CUSTOM_PROPERTY_KEY_RE.test(viewCustomPropertyKey)) {
+            q = q.filter(subscriberViewCustomPropertyPath(viewCustomPropertyKey), 'ilike', `%${viewCustomPropertyValue}%`);
+        }
+        if (viewFilters && viewFilters.show_test !== true)
+            q = q.not('is_test', 'is', true);
         if (company_id)
             q = q.eq('company_id', company_id);
         if (site_id) {
@@ -623,6 +860,32 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 return { content: [{ type: 'text', text: '[]' }] };
             q = q.in('id', ids);
         }
+        const statusSiteId = viewSiteId ?? site_id;
+        if (statusSiteId && ['active', 'unsubscribed', 'not_subscribed'].includes(viewStatus)) {
+            const { data: siteSubscriptions, error: siteSubscriptionsError } = await db()
+                .from('site_subscriptions')
+                .select('contact_id, subscribed')
+                .eq('site_id', statusSiteId);
+            if (siteSubscriptionsError)
+                return txt(`Error: ${siteSubscriptionsError.message}`);
+            if (viewStatus === 'not_subscribed') {
+                const subscribedIds = (siteSubscriptions ?? [])
+                    .map((subscription) => subscription.contact_id)
+                    .filter(Boolean);
+                if (subscribedIds.length > 0)
+                    q = q.not('id', 'in', `(${subscribedIds.join(',')})`);
+            }
+            else {
+                const shouldBeSubscribed = viewStatus === 'active';
+                const matchingIds = (siteSubscriptions ?? [])
+                    .filter((subscription) => subscription.subscribed === shouldBeSubscribed)
+                    .map((subscription) => subscription.contact_id)
+                    .filter(Boolean);
+                if (!matchingIds.length)
+                    return txt('[]');
+                q = q.in('id', matchingIds);
+            }
+        }
         if (company_domain) {
             const { data: companies } = await db()
                 .from('companies')
@@ -639,6 +902,137 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
+    server.registerTool('list_subscriber_views', {
+        title: 'List Subscriber Views',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'List saved subscriber views for the current project in creation order.',
+        inputSchema: {},
+    }, async () => {
+        const { data, error } = await db()
+            .from('subscriber_list_views')
+            .select('id, name, view_mode, columns, filters, created_by, created_at, updated_at')
+            .eq('project_id', getProjectId())
+            .order('created_at', { ascending: true });
+        if (error)
+            return txt(`Error: ${error.message}`);
+        return j({ views: data ?? [] });
+    });
+    server.registerTool('create_subscriber_view', {
+        title: 'Create Subscriber View',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: 'Create a saved subscriber view for the current project. The saved filters can be applied with list_subscribers view_id.',
+        inputSchema: {
+            name: z.string().min(1),
+            view_mode: z.enum(['table', 'grid']),
+            columns: subscriberViewColumnsSchema.optional(),
+            filters: z.record(z.string(), z.unknown()).optional(),
+        },
+    }, async ({ name, view_mode, columns, filters }) => {
+        const normalizedName = name.trim().slice(0, SUBSCRIBER_VIEW_MAX_NAME_LENGTH);
+        if (!normalizedName)
+            return txt('Error: name is required');
+        const { data, error } = await db()
+            .from('subscriber_list_views')
+            .insert({
+            project_id: getProjectId(),
+            created_by: null,
+            name: normalizedName,
+            view_mode,
+            columns: normalizeSubscriberViewColumns(columns),
+            filters: normalizeSubscriberViewFilters(filters),
+        })
+            .select('id, name, view_mode, columns, filters, created_by, created_at, updated_at')
+            .maybeSingle();
+        if (error?.code === '23505')
+            return txt(`Error: A view named "${normalizedName}" already exists`);
+        if (error)
+            return txt(`Error: ${error.message}`);
+        return j({ view: data });
+    });
+    server.registerTool('update_subscriber_view', {
+        title: 'Update Subscriber View',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'Update selected fields on a saved subscriber view owned by the current project.',
+        inputSchema: {
+            view_id: z.string().uuid(),
+            name: z.string().optional(),
+            view_mode: z.enum(['table', 'grid']).optional(),
+            columns: subscriberViewColumnsSchema.optional(),
+            filters: z.record(z.string(), z.unknown()).optional(),
+        },
+    }, async ({ view_id, name, view_mode, columns, filters }) => {
+        if (name === undefined && view_mode === undefined && columns === undefined && filters === undefined) {
+            return txt('Nothing to update');
+        }
+        const updates = {};
+        if (name !== undefined) {
+            const normalizedName = name.trim().slice(0, SUBSCRIBER_VIEW_MAX_NAME_LENGTH);
+            if (!normalizedName)
+                return txt('Error: name is required');
+            updates.name = normalizedName;
+        }
+        if (view_mode !== undefined)
+            updates.view_mode = view_mode;
+        if (columns !== undefined)
+            updates.columns = normalizeSubscriberViewColumns(columns);
+        if (filters !== undefined)
+            updates.filters = normalizeSubscriberViewFilters(filters);
+        const { data, error } = await db()
+            .from('subscriber_list_views')
+            .update(updates)
+            .eq('id', view_id)
+            .eq('project_id', getProjectId())
+            .select('id, name, view_mode, columns, filters, created_by, created_at, updated_at')
+            .maybeSingle();
+        if (error?.code === '23505')
+            return txt('Error: A view with that name already exists');
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!data)
+            return txt('View not found');
+        return j({ view: data });
+    });
+    server.registerTool('delete_subscriber_view', {
+        title: 'Delete Subscriber View',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: 'Delete a saved subscriber view owned by the current project.',
+        inputSchema: {
+            view_id: z.string().uuid(),
+        },
+    }, async ({ view_id }) => {
+        const { data, error } = await db()
+            .from('subscriber_list_views')
+            .delete()
+            .eq('id', view_id)
+            .eq('project_id', getProjectId())
+            .select('id')
+            .maybeSingle();
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!data)
+            return txt('View not found');
+        return j({ deleted: true, view_id });
+    });
     server.registerTool('list_companies', {
         title: 'List Companies',
         annotations: {
@@ -741,11 +1135,11 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .maybeSingle();
         const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
         if (company_name || company_domain) {
-            row.custom_properties = {
-                ...(typeof row.custom_properties === 'object' && row.custom_properties ? row.custom_properties : {}),
+            const orgId = await getProjectOrgId(projectId);
+            row.custom_properties = await normalizeMcpContactPropertyPatch({
                 ...(company_name ? { company_name } : {}),
                 ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
-            };
+            }, { orgId, projectId });
         }
         if (!needsConfirm)
             row.opted_in_at = new Date().toISOString();
@@ -1086,6 +1480,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         const projectId = getProjectId();
         const embedOk = await hasCompaniesEmbed(projectId);
         const updates = {};
+        let customPropertyChanges = [];
         if (email !== undefined)
             updates.email = email;
         if (first_name !== undefined)
@@ -1110,12 +1505,24 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .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 ?? {}),
-                ...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()
@@ -1124,10 +1531,14 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 .eq('id', contact_id)
                 .eq('project_id', projectId)
                 .maybeSingle();
-            updates.custom_properties = {
-                ...(existing?.custom_properties ?? {}),
+            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 (!Object.keys(updates).length)
@@ -1142,6 +1553,14 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .single();
         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 },
+            });
+        }
         await writeBackMcpContact(projectId, data, {
             ...(updates.email !== undefined ? { email: updates.email } : {}),
             ...(updates.first_name !== undefined ? { first_name: updates.first_name } : {}),
@@ -1211,11 +1630,17 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         const enriched = await enrichContactFromProviders(projectId, contact.email, provider);
         if (!enriched)
             return j({ contact, enriched: false, applied_fields: [] });
+        const orgId = await getProjectOrgId(projectId);
+        const normalizedEnrichedProperties = await normalizeMcpContactPropertyPatch(enriched.properties, {
+            orgId,
+            projectId,
+            subscriberId: contact_id,
+        });
         const nextProperties = {
             ...(contact.custom_properties ?? {}),
             [enriched.provider]: {
                 ...((contact.custom_properties ?? {})[enriched.provider] ?? {}),
-                ...enriched.properties,
+                ...normalizedEnrichedProperties,
             },
         };
         const companyId = await resolveCompanyId(projectId, {
@@ -1313,6 +1738,76 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         }
         return j({ updated, total: contact_ids.length, add_tags, remove_tags });
     });
+    server.registerTool('bulk_update_subscribers', {
+        title: 'Bulk Update Subscribers',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'Merge custom_properties into many contacts at once. Same merge semantics as update_subscriber, applied across a batch.',
+        inputSchema: {
+            contact_ids: z.array(z.string().uuid()).min(1),
+            custom_properties: z.record(z.string(), z.unknown()).describe('Merged into each contact\'s existing custom_properties; a key set to null deletes that key'),
+        },
+    }, async ({ contact_ids, custom_properties }) => {
+        const projectId = getProjectId();
+        const orgId = await getProjectOrgId(projectId);
+        const fields = await loadContactPropertyDefinitions(projectId);
+        const anomalyLogger = new ContactPropertyAnomalyLogger({
+            orgId,
+            projectId,
+            subscriberId: null,
+            pipeline: 'mcp_subscriber_tools',
+        });
+        const normalizedPatch = await normalizeMcpContactPropertyPatch(custom_properties, {
+            orgId,
+            projectId,
+            preserveNullDeletions: true,
+            fields,
+            anomalyLogger,
+        });
+        await anomalyLogger.flush(db());
+        let updated = 0;
+        for (const cid of contact_ids) {
+            const { data: contact } = await db()
+                .from('subscribers')
+                .select('id, email, first_name, last_name, custom_properties')
+                .eq('id', cid)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (!contact)
+                continue;
+            const changes = diffCustomProperties(contact.custom_properties ?? null, normalizedPatch);
+            const merged = {
+                ...(contact.custom_properties ?? {}),
+                ...normalizedPatch,
+            };
+            for (const [key, value] of Object.entries(normalizedPatch)) {
+                if (value === null)
+                    delete merged[key];
+            }
+            const { error } = await db()
+                .from('subscribers')
+                .update({ custom_properties: merged, updated_at: new Date().toISOString() })
+                .eq('id', cid)
+                .eq('project_id', projectId);
+            if (error)
+                continue;
+            updated++;
+            if (changes.length > 0) {
+                logAudit({
+                    action: 'contact.custom_properties_changed',
+                    resourceType: 'contact',
+                    resourceId: cid,
+                    details: { changes },
+                });
+            }
+            await writeBackMcpContact(projectId, contact, { custom_properties: merged });
+        }
+        return j({ updated, total: contact_ids.length });
+    });
     server.registerTool('estimate_segment_size', {
         title: 'Estimate Segment Size',
         annotations: {
@@ -1370,13 +1865,9 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             q = q.contains('tags', [params.tag]);
         if (params.company_id)
             q = q.eq('company_id', params.company_id);
+        const fieldTypes = params.custom_property ? await loadContactPropertyDefinitions(projectId) : {};
         if (params.custom_property) {
-            const eqIdx = params.custom_property.indexOf('=');
-            if (eqIdx > 0) {
-                const key = params.custom_property.slice(0, eqIdx);
-                const val = params.custom_property.slice(eqIdx + 1);
-                q = q.contains('custom_properties', { [key]: val });
-            }
+            ({ query: q } = await applySegmentRules(q, { custom_property: params.custom_property }, db(), projectId, fieldTypes));
         }
         if (params.site_id) {
             const { data: subs } = await db()
@@ -1431,6 +1922,9 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             countQ = countQ.is('last_clicked_at', null);
         if (params.tag)
             countQ = countQ.contains('tags', [params.tag]);
+        if (params.custom_property) {
+            ({ query: countQ } = await applySegmentRules(countQ, { custom_property: params.custom_property }, db(), projectId, fieldTypes));
+        }
         const { count } = await countQ;
         return j({ total: count ?? (data ?? []).length, sample: data ?? [] });
     });
@@ -1801,4 +2295,238 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             note: '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('create_custom_field', {
+        title: 'Create Custom Field',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: 'Register a typed custom field definition for contact custom properties and segment filtering.',
+        inputSchema: {
+            key: z.string().trim().min(1).max(50).regex(CUSTOM_FIELD_KEY_RE, 'must be lowercase snake_case, e.g. "plan_tier"'),
+            label: z.string().trim().min(1),
+            type: z.enum(CUSTOM_FIELD_TYPES),
+            required: z.boolean().optional().default(false),
+            options: z.array(z.string()).optional(),
+            display_order: z.number().int().optional().default(0),
+        },
+    }, async ({ key, label, type, required, options, display_order }) => {
+        const optionsError = validateCustomFieldOptions(type, options);
+        if (optionsError)
+            return txt(`Error: ${optionsError}`);
+        const normalizedOptions = type === 'select' || type === 'multi_select'
+            ? normalizeCustomFieldOptions(options)
+            : null;
+        const projectId = getProjectId();
+        const orgId = await getProjectOrgId(projectId);
+        const { data, error } = await db()
+            .from('custom_field_definitions')
+            .insert({
+            org_id: orgId,
+            project_id: projectId,
+            key,
+            label,
+            type,
+            required: required ?? false,
+            options: normalizedOptions ?? null,
+            display_order: display_order ?? 0,
+        })
+            .select('id, key, label, type, required, options, display_order')
+            .single();
+        if (error) {
+            if (error.code === '23505')
+                return txt(`Error: A custom field with key "${key}" already exists.`);
+            return txt(`Error: ${error.message}`);
+        }
+        await logAudit({
+            action: 'custom_field.created',
+            resourceType: 'custom_field_definition',
+            resourceId: data.id,
+            details: { key },
+        });
+        return j(data);
+    });
+    server.registerTool('update_custom_field', {
+        title: 'Update Custom Field',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Update a custom field definition label, type, required state, options, or display order. The field key is immutable.',
+        inputSchema: {
+            id: z.string().uuid(),
+            label: z.string().trim().min(1).optional(),
+            type: z.enum(CUSTOM_FIELD_TYPES).optional(),
+            required: z.boolean().optional(),
+            options: z.array(z.string()).optional(),
+            display_order: z.number().int().optional(),
+        },
+    }, async ({ id, label, type, required, options, display_order }) => {
+        const projectId = getProjectId();
+        const { data: current, error: currentError } = await db()
+            .from('custom_field_definitions')
+            .select('id, key, label, type, required, options, display_order')
+            .eq('id', id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (currentError)
+            return txt(`Error: ${currentError.message}`);
+        if (!current)
+            return j({ error: 'Custom field not found', code: 'NOT_FOUND' });
+        const nextType = (type ?? current.type);
+        const nextOptions = options === undefined ? current.options : options;
+        const optionsError = validateCustomFieldOptions(nextType, nextOptions);
+        if (optionsError)
+            return txt(`Error: ${optionsError}`);
+        const normalizedOptions = nextType === 'select' || nextType === 'multi_select'
+            ? normalizeCustomFieldOptions(nextOptions)
+            : null;
+        const { data, error } = await db()
+            .from('custom_field_definitions')
+            .update({
+            label: label ?? current.label,
+            type: nextType,
+            required: required ?? current.required,
+            options: normalizedOptions,
+            display_order: display_order ?? current.display_order,
+            updated_at: new Date().toISOString(),
+        })
+            .eq('id', id)
+            .eq('project_id', projectId)
+            .select('id, key, label, type, required, options, display_order')
+            .maybeSingle();
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!data)
+            return j({ error: 'Custom field not found', code: 'NOT_FOUND' });
+        await logAudit({
+            action: 'custom_field.updated',
+            resourceType: 'custom_field_definition',
+            resourceId: data.id,
+            details: { key: data.key },
+        });
+        return j(data);
+    });
+    server.registerTool('delete_custom_field', {
+        title: 'Delete Custom Field',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        description: 'Delete a custom field definition without deleting existing contact values stored under that key.',
+        inputSchema: { id: z.string().uuid() },
+    }, async ({ id }) => {
+        const projectId = getProjectId();
+        const { data, error } = await db()
+            .from('custom_field_definitions')
+            .delete()
+            .eq('id', id)
+            .eq('project_id', projectId)
+            .select('id, key')
+            .maybeSingle();
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!data)
+            return j({ error: 'Custom field not found', code: 'NOT_FOUND' });
+        await logAudit({
+            action: 'custom_field.deleted',
+            resourceType: 'custom_field_definition',
+            resourceId: data.id,
+            details: { key: data.key },
+        });
+        return j({ deleted: true, id: data.id, key: data.key });
+    });
+    server.registerTool('get_contact_neighborhood', {
+        title: 'Get Contact Neighborhood',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'Operational neighborhood graph for one contact: identity, hygiene bucket, suppression, subscriptions, in-flight enrollments, send queue, recent email_log, scheduled newsletter issues, and open agent proposals. Includes a preview attention envelope (decided: false) — not a send decision.',
+        inputSchema: {
+            contact_id: z.string().uuid(),
+            window_hours: z.number().int().min(1).max(720).optional().default(168),
+        },
+    }, async ({ contact_id, window_hours }) => {
+        const { data, error } = await getContactNeighborhood(db(), getProjectId(), contact_id, window_hours);
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (data == null)
+            return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
+        return j({ ...data, attention: buildPreviewAttentionEnvelope() });
+    });
+    server.registerTool('get_scheduled_touches', {
+        title: 'Get Scheduled Touches',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'Cheap future-touch subset for one contact: enrollments with next_send_at in the window, queued send_queue rows, and scheduled newsletter issues. Includes a preview attention envelope (decided: false) — not a send decision.',
+        inputSchema: {
+            contact_id: z.string().uuid(),
+            window_hours: z.number().int().min(1).max(720).optional().default(168),
+        },
+    }, async ({ contact_id, window_hours }) => {
+        const { data, error } = await getScheduledTouches(db(), getProjectId(), contact_id, window_hours);
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (data == null)
+            return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
+        return j({ ...data, attention: buildPreviewAttentionEnvelope() });
+    });
+    server.registerTool('get_attention_decision', {
+        title: 'Get Attention Decision',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'Poll for the canonical enqueue-time attention decision (decided: true) on a send or hold. Provide email_log_id for a respond decision, or enrollment_id for a hold with no log row. Returns { decided: false } if the target exists but no decision has been written yet — do not treat launch_campaign / enroll_* / broadcast_to_segment success as a send decision.',
+        inputSchema: {
+            email_log_id: z.string().uuid().optional(),
+            enrollment_id: z.string().uuid().optional(),
+        },
+    }, async ({ email_log_id, enrollment_id }) => {
+        if (!email_log_id && !enrollment_id) {
+            return j({ error: 'Provide email_log_id or enrollment_id', code: 'BAD_REQUEST' });
+        }
+        const { data, error } = await getAttentionDecision(db(), getProjectId(), {
+            emailLogId: email_log_id,
+            enrollmentId: enrollment_id,
+        });
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (data == null)
+            return j({ error: 'Not found', code: 'NOT_FOUND' });
+        return j(data);
+    });
+    // Resource registration is additive; mcp-proxy may ignore it. Skip safely when
+    // the server proxy (tool-group scanner) does not expose registerResource.
+    const registerResource = server.registerResource?.bind(server);
+    if (typeof registerResource === 'function') {
+        registerResource('contact-neighborhood', new ResourceTemplate('sendinel://contacts/{contact_id}/neighborhood', { list: undefined }), {
+            title: 'Contact neighborhood',
+            description: 'Operational graph for one contact (preview, not a send decision).',
+        }, async (uri, vars) => {
+            const contactId = String(vars.contact_id ?? '');
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(contactId)) {
+                return {
+                    contents: [{
+                            uri: uri.href,
+                            mimeType: 'application/json',
+                            text: JSON.stringify({ error: 'Invalid contact_id', code: 'BAD_REQUEST' }),
+                        }],
+                };
+            }
+            const { data, error } = await getContactNeighborhood(db(), getProjectId(), contactId);
+            const payload = error
+                ? { error: error.message }
+                : data == null
+                    ? { error: 'Subscriber not found', code: 'NOT_FOUND' }
+                    : data;
+            return {
+                contents: [{
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(payload, null, 2),
+                    }],
+            };
+        });
+    }
 }