@sendinel/mcp-server 1.0.0

package/build/tools/contacts.js

@@ -0,0 +1,1483 @@
+import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
+import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
+import { z } from 'zod';
+import { db } from '../db.js';
+import { getProjectId } from '../project.js';
+import { checkPlanLimit } from '../plan-limits.js';
+import { logConsent, logAudit } from '../audit.js';
+import { requestApproval, checkApproval } from '../lib/action-approvals.js';
+import { decrypt } from '../crypto.js';
+import { normalizeActiveCampaignAccountUrl } from '../lib/url-validation.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));
+function daysAgo(days) {
+    return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+}
+function bucketSubscriber(c) {
+    if (!c.last_engaged_at)
+        return 'sunset_candidates';
+    const days = Math.floor((Date.now() - new Date(c.last_engaged_at).getTime()) / 86400000);
+    if (days <= 30)
+        return 'active';
+    if (days <= 90)
+        return 'cooling';
+    if (days <= 180)
+        return 'dormant';
+    return 'sunset_candidates';
+}
+function activePaying(c) {
+    const props = c.custom_properties ?? {};
+    const status = String(props.subscription_status ?? props.stripe_subscription_status ?? '').toLowerCase();
+    return Boolean(props.stripe_customer_id) && ['active', 'trialing', 'past_due'].includes(status);
+}
+function normalizeCompanyName(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim().replace(/\s+/g, ' ');
+    return normalized || null;
+}
+function normalizeCompanyKey(value) {
+    const normalized = normalizeCompanyName(value);
+    return normalized ? normalized.toLowerCase() : null;
+}
+function normalizeCompanyDomain(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    return normalized || null;
+}
+function normalizeEmail(value) {
+    return String(value ?? '').trim().toLowerCase();
+}
+const companiesEmbedCache = new Map();
+function isMissingRelationshipError(error) {
+    if (!error)
+        return false;
+    if (error.code === 'PGRST200')
+        return true;
+    return /could not find a relationship/i.test(error.message ?? '');
+}
+async function hasCompaniesEmbed(projectId) {
+    const cached = companiesEmbedCache.get(projectId);
+    if (cached !== undefined)
+        return cached;
+    const { error } = await db()
+        .from('subscribers')
+        .select('id, company:companies(id)')
+        .eq('project_id', projectId)
+        .limit(1);
+    const available = !isMissingRelationshipError(error);
+    companiesEmbedCache.set(projectId, available);
+    return available;
+}
+function aggregateCompanyMetrics(rows) {
+    const now = Date.now();
+    let contactCount = 0;
+    let activeCount = 0;
+    let engaged30d = 0;
+    let totalOpens = 0;
+    let totalClicks = 0;
+    let scoreSum = 0;
+    let scoreCount = 0;
+    let lastEngagedAt = null;
+    for (const row of rows) {
+        contactCount += 1;
+        const stage = String(row.lifecycle_stage ?? '').toLowerCase();
+        if (['active', 'trial', 'customer'].includes(stage))
+            activeCount += 1;
+        const lastEngaged = typeof row.last_engaged_at === 'string' ? row.last_engaged_at : null;
+        if (lastEngaged) {
+            const engagedAtMs = new Date(lastEngaged).getTime();
+            if (Number.isFinite(engagedAtMs) && (now - engagedAtMs) <= 30 * 24 * 60 * 60 * 1000)
+                engaged30d += 1;
+            if (!lastEngagedAt || lastEngaged > lastEngagedAt)
+                lastEngagedAt = lastEngaged;
+        }
+        totalOpens += Number(row.total_opens ?? 0);
+        totalClicks += Number(row.total_clicks ?? 0);
+        if (typeof row.engagement_score === 'number' && Number.isFinite(row.engagement_score)) {
+            scoreSum += row.engagement_score;
+            scoreCount += 1;
+        }
+    }
+    return {
+        contact_count: contactCount,
+        active_contact_count: activeCount,
+        engaged_30d_count: engaged30d,
+        avg_engagement_score: scoreCount > 0 ? Number((scoreSum / scoreCount).toFixed(1)) : null,
+        total_opens: totalOpens,
+        total_clicks: totalClicks,
+        last_engaged_at: lastEngagedAt,
+    };
+}
+function primaryContactValue(value) {
+    if (typeof value === 'string')
+        return value.trim() || null;
+    if (Array.isArray(value)) {
+        const primary = value.find((item) => item && typeof item === 'object' && item.primary && item.value);
+        const fallback = value.find((item) => item && typeof item === 'object' && item.value);
+        const selected = primary ?? fallback;
+        return selected && typeof selected === 'object' ? String(selected.value ?? '').trim() || null : null;
+    }
+    return null;
+}
+const SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, total_opens, total_clicks, engagement_score, lifecycle_stage';
+const SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, total_opens, total_clicks, engagement_score, lifecycle_stage';
+const SEGMENT_SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_opens, total_clicks';
+const SEGMENT_SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_opens, total_clicks';
+const UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), custom_properties, tags';
+const UPDATE_SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, custom_properties, tags';
+const GET_SUBSCRIBER_SELECT_WITH_COMPANY = '*, company:companies(id, name, domain), site_subscriptions(site_id, subscribed)';
+const GET_SUBSCRIBER_SELECT_NO_COMPANY = '*, site_subscriptions(site_id, subscribed)';
+const CONTACT_ENRICHMENT_ADAPTERS = createContactEnrichmentAdapters({
+    normalizeActiveCampaignAccountUrl,
+});
+async function enrichContactFromProviders(projectId, email, provider) {
+    const { data: connections, error } = await db()
+        .from('platform_connections')
+        .select('platform, credentials_enc')
+        .eq('project_id', projectId)
+        .eq('is_active', true)
+        .in('platform', provider ? [provider] : [...CONTACT_ENRICHMENT_PROVIDERS]);
+    if (error)
+        throw new Error(error.message);
+    return enrichContactFromConnections({
+        connections: (connections ?? []),
+        email,
+        provider,
+        adapters: CONTACT_ENRICHMENT_ADAPTERS,
+        decryptCredentials(credentialsEnc) {
+            return JSON.parse(decrypt(credentialsEnc));
+        },
+    });
+}
+async function resolveCompanyId(projectId, input) {
+    if (input.company_id)
+        return input.company_id;
+    const companyName = normalizeCompanyName(input.company_name);
+    const companyKey = normalizeCompanyKey(input.company_name);
+    const companyDomain = normalizeCompanyDomain(input.company_domain);
+    if (!companyName && !companyDomain)
+        return undefined;
+    let existing = null;
+    if (companyDomain) {
+        const { data } = await db()
+            .from('companies')
+            .select('id')
+            .eq('project_id', projectId)
+            .eq('domain', companyDomain)
+            .maybeSingle();
+        existing = data ?? null;
+    }
+    if (!existing && companyKey) {
+        const { data } = await db()
+            .from('companies')
+            .select('id')
+            .eq('project_id', projectId)
+            .eq('name_key', companyKey)
+            .maybeSingle();
+        existing = data ?? null;
+    }
+    if (existing)
+        return existing.id;
+    const { data, error } = await db()
+        .from('companies')
+        .insert({
+        project_id: projectId,
+        name: companyName ?? companyDomain ?? 'Unknown company',
+        name_key: companyKey ?? companyDomain,
+        domain: companyDomain,
+    })
+        .select('id')
+        .single();
+    if (error)
+        throw error;
+    return data.id;
+}
+async function exportSubscriberData(projectId, contactId) {
+    const { data: contact, error: contactError } = await db()
+        .from('subscribers')
+        .select('id, email, tags, custom_properties, source, source_site, lifecycle_stage, created_at, opted_in_at, global_unsubscribed')
+        .eq('id', contactId)
+        .eq('project_id', projectId)
+        .maybeSingle();
+    if (contactError)
+        return { error: contactError.message };
+    if (!contact)
+        return { error: 'Subscriber not found', code: 'NOT_FOUND' };
+    const { data: emailHistory, error: logError } = await db()
+        .from('email_log')
+        .select('id, subject, sent_at, status, opened_at, clicked_at')
+        .eq('project_id', projectId)
+        .eq('contact_id', contactId)
+        .not('to_email', 'like', 'sha256:%')
+        .order('sent_at', { ascending: false });
+    if (logError)
+        return { error: logError.message };
+    const { data: suppression, error: suppressionError } = await db()
+        .from('suppressions')
+        .select('reason, created_at')
+        .eq('project_id', projectId)
+        .eq('email', contact.email)
+        .not('email', 'like', 'sha256:%')
+        .maybeSingle();
+    if (suppressionError)
+        return { error: suppressionError.message };
+    return {
+        contact: {
+            id: contact.id,
+            email: contact.email,
+            tags: contact.tags ?? [],
+            custom_properties: contact.custom_properties ?? {},
+            source: contact.source ?? null,
+            source_site: contact.source_site ?? null,
+            lifecycle_stage: contact.lifecycle_stage ?? null,
+            created_at: contact.created_at ?? null,
+            opted_in_at: contact.opted_in_at ?? null,
+            global_unsubscribed: contact.global_unsubscribed ?? null,
+        },
+        emailHistory: emailHistory ?? [],
+        suppressionStatus: {
+            suppressed: !!suppression,
+            reason: suppression?.reason ?? null,
+            created_at: suppression?.created_at ?? null,
+        },
+    };
+}
+export function registerContactTools(server) {
+    server.registerTool('get_subscriber_timeline', {
+        description: 'Get a merged activity timeline for a contact.',
+        inputSchema: { subscriber_id: z.string().uuid(), limit: z.number().int().min(1).max(100).optional().default(50) },
+    }, async ({ subscriber_id, limit = 50 }) => {
+        const projectId = getProjectId();
+        const { data: contact } = await db().from('subscribers').select('id, email').eq('project_id', projectId).eq('id', subscriber_id).maybeSingle();
+        if (!contact)
+            return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
+        const [emails, enrollments, events, suppressions] = await Promise.all([
+            db().from('email_log').select('id, status, subject, created_at, campaign_id').eq('project_id', projectId).eq('contact_id', subscriber_id).limit(limit),
+            db().from('campaign_enrollments').select('id, status, enrolled_at, completed_at, campaigns(name)').eq('contact_id', subscriber_id).limit(limit),
+            db().from('event_log').select('id, event_name, source, properties, created_at').eq('project_id', projectId).eq('contact_id', subscriber_id).limit(limit),
+            db().from('suppressions').select('id, reason, created_at').eq('project_id', projectId).eq('email', contact.email).limit(limit),
+        ]);
+        const timeline = [
+            ...(emails.data ?? []).map((row) => ({ id: `email:${row.id}`, type: `email_${row.status}`, title: `Email ${row.status}: ${row.subject ?? '(no subject)'}`, metadata: row, created_at: row.created_at })),
+            ...(enrollments.data ?? []).map((row) => ({ id: `enrollment:${row.id}`, type: row.status === 'completed' ? 'completed' : 'enrolled', title: row.status === 'completed' ? 'Campaign completed' : 'Campaign enrollment', metadata: row, created_at: row.completed_at ?? row.enrolled_at })),
+            ...(events.data ?? []).map((row) => ({ id: `api_event:${row.id}`, type: 'api_event', title: `API event received: ${row.event_name}`, metadata: row, created_at: row.created_at })),
+            ...(suppressions.data ?? []).map((row) => ({ id: `suppression:${row.id}`, type: 'suppressed', title: `Suppressed: ${row.reason}`, metadata: row, created_at: row.created_at })),
+        ].sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()).slice(0, limit);
+        return j({ events: timeline });
+    });
+    server.registerTool('get_hygiene_config', {
+        description: 'Get list hygiene automation config.',
+        inputSchema: {},
+    }, async () => {
+        const { data, error } = await db().from('list_hygiene_config').select('*').eq('project_id', getProjectId()).maybeSingle();
+        if (error)
+            return j({ error: error.message });
+        return j(data ?? { enabled: false, inactive_days: 90, action: 'tag', tag_name: 'cold', suppress_after_days: 180, last_run_at: null });
+    });
+    server.registerTool('update_hygiene_config', {
+        description: 'Update list hygiene automation config.',
+        inputSchema: {
+            enabled: z.boolean().optional(),
+            inactive_days: z.number().int().min(1).optional(),
+            action: z.enum(['tag', 'suppress', 'tag_and_suppress']).optional(),
+            tag_name: z.string().optional(),
+            suppress_after_days: z.number().int().min(1).optional(),
+        },
+    }, async (config) => {
+        const { error } = await db().from('list_hygiene_config').upsert({ project_id: getProjectId(), ...config, updated_at: new Date().toISOString() }, { onConflict: 'project_id' });
+        if (error)
+            return j({ error: error.message });
+        return j({ updated: true });
+    });
+    server.registerTool('run_list_hygiene', {
+        description: 'Run list hygiene immediately for the project.',
+        inputSchema: {},
+    }, async () => {
+        const projectId = getProjectId();
+        const cutoff = daysAgo(90);
+        const { data: contacts } = await db().from('subscribers').select('id, email, tags, last_engaged_at').eq('project_id', projectId).lt('last_engaged_at', cutoff).limit(1000);
+        const ids = (contacts ?? []).map((contact) => contact.id);
+        if (ids.length) {
+            await db().from('subscribers').update({ tags: ['cold'] }).eq('project_id', projectId).in('id', ids);
+        }
+        return j({ tagged: ids.length, suppressed: 0, skipped: 0 });
+    });
+    server.registerTool('list_hygiene_audit', {
+        description: 'Audit list engagement health and identify sunset candidates while excluding active paying customers.',
+        inputSchema: {
+            siteId: z.string().uuid(),
+            lookbackDays: z.number().int().min(30).max(730).optional().default(180),
+        },
+    }, async ({ siteId, lookbackDays = 180 }) => {
+        const projectId = getProjectId();
+        const { data: subs } = await db()
+            .from('site_subscriptions')
+            .select('contact_id')
+            .eq('site_id', siteId)
+            .eq('subscribed', true);
+        const ids = (subs ?? []).map((s) => s.contact_id);
+        if (!ids.length)
+            return j({
+                summary: { total: 0, active: 0, cooling: 0, dormant: 0, sunset_candidates: 0, active_paying_low_engagement: 0 },
+                sunset_candidates: [],
+                active_paying_low_engagement: [],
+                recommendation: 'No subscribed contacts found for this site.',
+                lookback_days: lookbackDays,
+            });
+        const { data: contacts, error } = await db()
+            .from('subscribers')
+            .select('id, email, last_engaged_at, total_opens, total_clicks, total_emails_sent, custom_properties')
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false)
+            .in('id', ids)
+            .limit(5000);
+        if (error)
+            return txt(`Error: ${error.message}`);
+        const summary = { total: contacts?.length ?? 0, active: 0, cooling: 0, dormant: 0, sunset_candidates: 0, active_paying_low_engagement: 0 };
+        const sunset = [];
+        const payingLowEngagement = [];
+        const cutoff = daysAgo(lookbackDays);
+        for (const c of contacts ?? []) {
+            const bucket = bucketSubscriber(c);
+            summary[bucket]++;
+            const noEngagement = !c.last_engaged_at || c.last_engaged_at < cutoff;
+            const noOpensClicks = (c.total_opens ?? 0) === 0 && (c.total_clicks ?? 0) === 0;
+            const sentEnough = (c.total_emails_sent ?? 0) >= 5;
+            if (noEngagement && noOpensClicks && sentEnough) {
+                if (activePaying(c)) {
+                    payingLowEngagement.push(c.id);
+                }
+                else {
+                    sunset.push(c.id);
+                }
+            }
+        }
+        summary.sunset_candidates = sunset.length;
+        summary.active_paying_low_engagement = payingLowEngagement.length;
+        const percent = summary.total ? Math.round((sunset.length / summary.total) * 100) : 0;
+        const estimatedMonthlySavings = Math.round(sunset.length * 0.01);
+        return j({
+            summary,
+            sunset_candidates: sunset.slice(0, 500),
+            active_paying_low_engagement: payingLowEngagement.slice(0, 500),
+            recommendation: `${sunset.length} contacts have not engaged in ${lookbackDays}+ days after 5+ sends. Suppressing them would reduce list size by ${percent}% and could reduce Klaviyo active-profile billing by approximately $${estimatedMonthlySavings}/mo if migrated.`,
+            estimated_send_volume_reduction: sunset.length,
+            estimated_klaviyo_monthly_reduction_usd: estimatedMonthlySavings,
+            lookback_days: lookbackDays,
+        });
+    });
+    server.registerTool('list_win_back_draft', {
+        description: 'Draft a human-approved win-back email for dormant or sunset contacts. Does not enqueue or send.',
+        inputSchema: {
+            siteId: z.string().uuid(),
+            segmentId: z.string().uuid().optional(),
+            cohort: z.enum(['dormant', 'sunset_candidates']).optional().default('dormant'),
+        },
+    }, async ({ siteId, segmentId, cohort = 'dormant' }) => {
+        const projectId = getProjectId();
+        const [{ data: site }, { data: subs }] = await Promise.all([
+            db().from('sites').select('id, name, sending_domain, brand_voice, projects(org_id, organizations(brand_settings))').eq('id', siteId).eq('project_id', projectId).maybeSingle(),
+            db().from('site_subscriptions').select('contact_id').eq('site_id', siteId).eq('subscribed', true),
+        ]);
+        if (!site)
+            return j({ error: 'Site not found', code: 'NOT_FOUND' });
+        const ids = (subs ?? []).map((s) => s.contact_id);
+        if (!ids.length)
+            return j({ error: 'No subscribed contacts for this site', code: 'EMPTY_COHORT' });
+        let q = db()
+            .from('subscribers')
+            .select('id, email, first_name, created_at, last_engaged_at, tags, total_opens, total_clicks, total_emails_sent')
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false)
+            .in('id', ids)
+            .limit(50);
+        if (cohort === 'dormant')
+            q = q.lt('last_engaged_at', daysAgo(90)).gte('last_engaged_at', daysAgo(180));
+        else
+            q = q.or(`last_engaged_at.is.null,last_engaged_at.lt.${daysAgo(180)}`).eq('total_opens', 0).eq('total_clicks', 0).gte('total_emails_sent', 5);
+        if (segmentId)
+            q = q.contains('tags', [`segment:${segmentId}`]);
+        const { data: sample, error } = await q;
+        if (error)
+            return txt(`Error: ${error.message}`);
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey)
+            return j({ error: 'ANTHROPIC_API_KEY not configured', code: 'AI_UNAVAILABLE' });
+        const client = new Anthropic({ apiKey });
+        const prompt = `Draft a win-back email for ${site.name}.
+Cohort: ${cohort}
+Sample contacts: ${JSON.stringify((sample ?? []).slice(0, 10))}
+Brand settings: ${JSON.stringify({ site_brand_voice: site.brand_voice, org_brand_settings: site.projects?.organizations?.brand_settings })}
+
+Return JSON only with subject, preview_text, body_html, cta_text, reasoning.
+Requirements: urgency without desperation, acknowledge the gap, one clear CTA, visible one-click unsubscribe link in body using {{unsubscribe_url}}, no auto-send language.`;
+        const response = await client.messages.create({
+            model: getAnthropicModelId(),
+            max_tokens: 1200,
+            system: 'You are an expert lifecycle email strategist. Return valid JSON only.',
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const text = response.content.map((part) => part.type === 'text' ? part.text : '').join('').trim();
+        let draft = text;
+        try {
+            draft = JSON.parse(text);
+        }
+        catch { }
+        return j({
+            site_id: siteId,
+            segment_id: segmentId ?? null,
+            cohort,
+            sample_size: sample?.length ?? 0,
+            draft,
+            auto_enqueued: false,
+            follow_up_note: 'Contacts that do not respond to this win-back should be auto-suppressed by a follow-up automation after the send window.',
+        });
+    });
+    server.registerTool('list_subscribers', {
+        description: 'List contacts, optionally filtered by site and/or search term',
+        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'),
+            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 }) => {
+        const projectId = getProjectId();
+        const embedOk = await hasCompaniesEmbed(projectId);
+        let q = db()
+            .from('subscribers')
+            .select(embedOk ? SUBSCRIBER_SELECT_WITH_COMPANY : SUBSCRIBER_SELECT_NO_COMPANY)
+            .eq('project_id', projectId)
+            .order('created_at', { ascending: false })
+            .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 (company_id)
+            q = q.eq('company_id', company_id);
+        if (site_id) {
+            const { data: subs } = await db()
+                .from('site_subscriptions')
+                .select('contact_id')
+                .eq('site_id', site_id)
+                .eq('subscribed', true);
+            const ids = (subs ?? []).map((s) => s.contact_id);
+            if (!ids.length)
+                return { content: [{ type: 'text', text: '[]' }] };
+            q = q.in('id', ids);
+        }
+        if (company_domain) {
+            const { data: companies } = await db()
+                .from('companies')
+                .select('id')
+                .eq('project_id', projectId)
+                .eq('domain', company_domain.trim().toLowerCase());
+            const ids = (companies ?? []).map((company) => company.id);
+            if (!ids.length)
+                return { content: [{ type: 'text', text: '[]' }] };
+            q = q.in('company_id', ids);
+        }
+        const { data, error } = await q;
+        if (error)
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerTool('list_companies', {
+        description: 'List linked companies for the current project with rolled-up contact engagement metrics.',
+        inputSchema: {
+            search: z.string().optional().describe('Partial match on company name or domain'),
+            limit: z.number().int().min(1).max(200).optional().default(50),
+        },
+    }, async ({ search, limit }) => {
+        const projectId = getProjectId();
+        let query = db()
+            .from('companies')
+            .select('id, name, domain, created_at')
+            .eq('project_id', projectId)
+            .order('name', { ascending: true })
+            .limit(limit ?? 50);
+        if (search) {
+            query = query.or(`name.ilike.%${search}%,domain.ilike.%${search}%`);
+        }
+        const { data: companies, error } = await query;
+        if (error)
+            return txt(`Error: ${error.message}`);
+        const rows = companies ?? [];
+        if (!rows.length)
+            return j([]);
+        const companyIds = rows.map((company) => company.id);
+        const { data: subscribers, error: subscriberError } = await db()
+            .from('subscribers')
+            .select('company_id, engagement_score, total_opens, total_clicks, lifecycle_stage, last_engaged_at')
+            .eq('project_id', projectId)
+            .in('company_id', companyIds);
+        if (subscriberError)
+            return txt(`Error: ${subscriberError.message}`);
+        const grouped = new Map();
+        for (const subscriber of subscribers ?? []) {
+            const companyId = typeof subscriber.company_id === 'string' ? subscriber.company_id : null;
+            if (!companyId)
+                continue;
+            const bucket = grouped.get(companyId) ?? [];
+            bucket.push(subscriber);
+            grouped.set(companyId, bucket);
+        }
+        return j(rows.map((company) => ({
+            ...company,
+            metrics: aggregateCompanyMetrics(grouped.get(company.id) ?? []),
+        })));
+    });
+    server.registerTool('add_subscriber', {
+        description: 'Add a contact and subscribe them to a site',
+        inputSchema: {
+            email: z.string().email(),
+            site_id: z.string().uuid(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            company_id: z.string().uuid().optional(),
+            company_name: z.string().optional(),
+            company_domain: z.string().optional(),
+            source: z.enum(['signup', 'import', 'form', 'manual']).optional().default('manual'),
+            utm_source: z.string().optional(),
+            utm_medium: z.string().optional(),
+            utm_campaign: z.string().optional(),
+            utm_content: z.string().optional(),
+            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 }) => {
+        const projectId = getProjectId();
+        const embedOk = await hasCompaniesEmbed(projectId);
+        const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
+        // 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 { content: [{ type: 'text', text: `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.` }] };
+        }
+        const limit = await checkPlanLimit('contacts');
+        if (!limit.allowed) {
+            return { content: [{ type: 'text', text: `Contact limit reached (${limit.current}/${limit.limit}). Upgrade to Pro for more contacts.` }] };
+        }
+        // Check if site requires double opt-in
+        const { data: siteInfo } = await db().from('sites').select('double_opt_in').eq('id', site_id).maybeSingle();
+        const needsConfirm = siteInfo?.double_opt_in === true;
+        const { data: existingContact } = await db()
+            .from('subscribers')
+            .select('id')
+            .eq('project_id', projectId)
+            .eq('email', email)
+            .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 : {}),
+                ...(company_name ? { company_name } : {}),
+                ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
+            };
+        }
+        if (!needsConfirm)
+            row.opted_in_at = new Date().toISOString();
+        if (!existingContact) {
+            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: contact, error: cErr } = await db()
+            .from('subscribers')
+            .upsert(row, { onConflict: 'project_id,email' })
+            .select(embedOk ? '*, company:companies(id, name, domain)' : '*')
+            .single();
+        if (cErr)
+            return { content: [{ type: 'text', text: `Error creating contact: ${cErr.message}` }] };
+        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 (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 });
+            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, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.' }, null, 2) }] };
+        }
+        logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
+        logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
+        return { content: [{ type: 'text', text: JSON.stringify(contact, null, 2) }] };
+    });
+    server.registerTool('import_subscribers', {
+        description: 'Bulk import contacts and subscribe them to a site. Max 200 per call.',
+        inputSchema: {
+            contacts: z.array(z.object({
+                email: z.string().email(),
+                first_name: z.string().optional(),
+                last_name: z.string().optional(),
+            })).min(1).max(200),
+            site_id: z.string().uuid(),
+        },
+    }, async ({ contacts, site_id }) => {
+        const projectId = getProjectId();
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        // Distribution list / system address block — same patterns as dashboard email-validation.ts
+        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 isDistro = (email) => {
+            const local = email.split('@')[0] ?? '';
+            return DISTRO_LOCAL_PARTS.has(local) || DISTRO_PATTERNS.some(p => p.test(local));
+        };
+        const seen = new Set();
+        const valid = [];
+        const skippedDistro = [];
+        for (const c of contacts) {
+            const email = c.email.trim().toLowerCase();
+            if (!emailRegex.test(email) || seen.has(email))
+                continue;
+            if (isDistro(email)) {
+                skippedDistro.push(email);
+                continue;
+            }
+            seen.add(email);
+            valid.push({ ...c, email });
+        }
+        if (!valid.length) {
+            const msg = skippedDistro.length
+                ? `No valid contacts to import. ${skippedDistro.length} address(es) blocked as distribution lists: ${skippedDistro.slice(0, 5).join(', ')}`
+                : 'No valid contacts to import.';
+            return { content: [{ type: 'text', text: msg }] };
+        }
+        // Check which already exist
+        const { data: existing } = await db()
+            .from('subscribers')
+            .select('email')
+            .eq('project_id', projectId)
+            .in('email', valid.map(c => c.email));
+        const existingEmails = new Set((existing ?? []).map((e) => e.email));
+        const newCount = valid.filter(c => !existingEmails.has(c.email)).length;
+        if (newCount > 0) {
+            const limit = await checkPlanLimit('contacts');
+            const remaining = limit.limit - limit.current;
+            if (newCount > remaining) {
+                return { content: [{ type: 'text', text: `Import would add ${newCount} new contacts but only ${remaining} slots remaining (${limit.current}/${limit.limit}). Upgrade to import more.` }] };
+            }
+        }
+        const rows = valid.map(c => ({
+            project_id: projectId,
+            email: c.email,
+            first_name: c.first_name || null,
+            last_name: c.last_name || null,
+            source: 'import',
+            opted_in_at: new Date().toISOString(),
+        }));
+        const { data: upserted, error: uErr } = await db()
+            .from('subscribers')
+            .upsert(rows, { onConflict: 'project_id,email', ignoreDuplicates: false })
+            .select('id, email');
+        if (uErr)
+            return { content: [{ type: 'text', text: `Error: ${uErr.message}` }] };
+        const contactRows = upserted ?? [];
+        const subRows = contactRows.map((c) => ({ contact_id: c.id, site_id, subscribed: true }));
+        if (subRows.length) {
+            await db().from('site_subscriptions').upsert(subRows, { onConflict: 'contact_id,site_id', ignoreDuplicates: true });
+        }
+        const created = contactRows.filter((c) => !existingEmails.has(c.email)).length;
+        const updated = contactRows.length - created;
+        return { content: [{ type: 'text', text: JSON.stringify({ created, updated, total: contactRows.length }, null, 2) }] };
+    });
+    server.registerTool('unsubscribe_subscriber', {
+        description: 'Globally unsubscribe a contact from all sites',
+        inputSchema: {
+            email: z.string().email(),
+        },
+    }, async ({ email }) => {
+        const now = new Date().toISOString();
+        const { data, error } = await db()
+            .from('subscribers')
+            .update({ global_unsubscribed: true, global_unsubscribed_at: now })
+            .eq('project_id', getProjectId())
+            .eq('email', email)
+            .select('id, email')
+            .single();
+        if (error)
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        if (data) {
+            // Cascade to site subscriptions
+            await db()
+                .from('site_subscriptions')
+                .update({ subscribed: false, unsubscribed_at: now, unsubscribe_reason: 'global_unsubscribe' })
+                .eq('contact_id', data.id)
+                .eq('subscribed', true);
+            logConsent({ contactId: data.id, action: 'revoke', consentType: 'email_marketing', source: 'mcp_unsubscribe' });
+            logAudit({ action: 'contact.unsubscribed', resourceType: 'contact', resourceId: data.id, details: { email } });
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ unsubscribed: true, ...data }, null, 2) }] };
+    });
+    server.registerTool('list_email_log', {
+        description: 'Recent email sends with status, filterable by site and/or recipient',
+        inputSchema: {
+            site_id: z.string().uuid().optional(),
+            contact_email: z.string().optional(),
+            status: z.enum(['sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained', 'failed']).optional(),
+            limit: z.number().int().min(1).max(200).optional().default(50),
+        },
+    }, async ({ site_id, contact_email, status, limit }) => {
+        let q = db()
+            .from('email_log')
+            .select('id, to_email, subject, status, sent_at, opened_at, clicked_at, bounced_at, site_id, campaign_id')
+            .eq('project_id', getProjectId())
+            .order('sent_at', { ascending: false })
+            .limit(limit ?? 50);
+        if (site_id)
+            q = q.eq('site_id', site_id);
+        if (status)
+            q = q.eq('status', status);
+        if (contact_email)
+            q = q.eq('to_email', contact_email);
+        const { data, error } = await q;
+        if (error)
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerTool('list_suppressions', {
+        description: 'List suppressed email addresses (hard bounces, complaints, manual blocks)',
+        inputSchema: {
+            limit: z.number().int().min(1).max(500).optional().default(100),
+            reason: z.enum(['hard_bounce', 'complaint', 'manual', 'repeated_soft_bounce']).optional(),
+        },
+    }, async ({ limit, reason }) => {
+        let q = db()
+            .from('suppressions')
+            .select('email, reason, source, created_at')
+            .eq('project_id', getProjectId())
+            .order('created_at', { ascending: false })
+            .limit(limit ?? 100);
+        if (reason)
+            q = q.eq('reason', reason);
+        const { data, error } = await q;
+        if (error)
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerTool('add_suppression', {
+        description: 'Manually add an email to the suppression list',
+        inputSchema: {
+            email: z.string().email(),
+            reason: z.enum(['hard_bounce', 'complaint', 'manual', 'repeated_soft_bounce']).default('manual'),
+            details: z.string().optional(),
+        },
+    }, async ({ email, reason, details }) => {
+        const { data, error } = await db()
+            .from('suppressions')
+            .upsert({ project_id: getProjectId(), email, reason, source: 'manual', details: details ? { note: details } : null }, { onConflict: 'project_id,email' })
+            .select()
+            .single();
+        if (error)
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerTool('list_subscribers_by_segment', {
+        description: 'List contacts filtered by engagement score range and/or lifecycle stage. Useful for building re-engagement campaigns or identifying high-value contacts.',
+        inputSchema: {
+            lifecycle_stage: z.enum(['new', 'active', 'cooling', 'cold', 'churned', 'lead', 'trial', 'customer', 'win-back']).optional(),
+            min_score: z.number().int().min(0).max(100).optional(),
+            max_score: z.number().int().min(0).max(100).optional(),
+            site_id: z.string().uuid().optional(),
+            company_id: z.string().uuid().optional(),
+            company_domain: z.string().optional(),
+            limit: z.number().int().min(1).max(200).optional().default(50),
+        },
+    }, async ({ lifecycle_stage, min_score, max_score, site_id, company_id, company_domain, limit }) => {
+        const projectId = getProjectId();
+        const embedOk = await hasCompaniesEmbed(projectId);
+        let q = db()
+            .from('subscribers')
+            .select(embedOk ? SEGMENT_SUBSCRIBER_SELECT_WITH_COMPANY : SEGMENT_SUBSCRIBER_SELECT_NO_COMPANY)
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false)
+            .order('engagement_score', { ascending: false })
+            .limit(limit ?? 50);
+        if (lifecycle_stage)
+            q = q.eq('lifecycle_stage', lifecycle_stage);
+        if (min_score !== undefined)
+            q = q.gte('engagement_score', min_score);
+        if (max_score !== undefined)
+            q = q.lte('engagement_score', max_score);
+        if (company_id)
+            q = q.eq('company_id', company_id);
+        if (site_id) {
+            const { data: subs } = await db()
+                .from('site_subscriptions')
+                .select('contact_id')
+                .eq('site_id', site_id)
+                .eq('subscribed', true);
+            const ids = (subs ?? []).map((s) => s.contact_id);
+            if (!ids.length)
+                return { content: [{ type: 'text', text: '[]' }] };
+            q = q.in('id', ids);
+        }
+        if (company_domain) {
+            const { data: companies } = await db()
+                .from('companies')
+                .select('id')
+                .eq('project_id', projectId)
+                .eq('domain', company_domain.trim().toLowerCase());
+            const ids = (companies ?? []).map((company) => company.id);
+            if (!ids.length)
+                return { content: [{ type: 'text', text: '[]' }] };
+            q = q.in('company_id', ids);
+        }
+        const { data, error } = await q;
+        if (error)
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerTool('update_subscriber', {
+        description: 'Update a contact\'s email, name, tags, or custom properties',
+        inputSchema: {
+            contact_id: z.string().uuid(),
+            email: z.string().email().optional(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            company_id: z.string().uuid().nullable().optional(),
+            company_name: z.string().nullable().optional(),
+            company_domain: z.string().nullable().optional(),
+            tags: z.array(z.string()).optional(),
+            custom_properties: z.record(z.unknown()).optional().describe('Merged into existing custom_properties'),
+        },
+    }, async ({ contact_id, email, first_name, last_name, company_id, company_name, company_domain, tags, custom_properties }) => {
+        const projectId = getProjectId();
+        const embedOk = await hasCompaniesEmbed(projectId);
+        const updates = {};
+        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();
+            updates.custom_properties = {
+                ...(existing?.custom_properties ?? {}),
+                ...custom_properties,
+                ...(company_name ? { company_name } : {}),
+                ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
+            };
+        }
+        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();
+            updates.custom_properties = {
+                ...(existing?.custom_properties ?? {}),
+                ...(company_name ? { company_name } : {}),
+                ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
+            };
+        }
+        if (!Object.keys(updates).length)
+            return txt('No fields to update.');
+        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)
+            return txt(`Error: ${error.message}`);
+        return j(data);
+    });
+    server.registerTool('get_subscriber', {
+        description: 'Get full contact details including site subscriptions, by ID or email',
+        inputSchema: {
+            contact_id: z.string().uuid().optional(),
+            email: z.string().email().optional(),
+        },
+    }, async ({ contact_id, email }) => {
+        const projectId = getProjectId();
+        const embedOk = await hasCompaniesEmbed(projectId);
+        let q = db()
+            .from('subscribers')
+            .select(embedOk ? GET_SUBSCRIBER_SELECT_WITH_COMPANY : GET_SUBSCRIBER_SELECT_NO_COMPANY)
+            .eq('project_id', projectId);
+        if (contact_id)
+            q = q.eq('id', contact_id);
+        else if (email)
+            q = q.eq('email', email);
+        else
+            return txt('Provide either contact_id or email.');
+        const { data, error } = await q.maybeSingle();
+        if (error)
+            return txt(`Error: ${error.message}`);
+        return j(data);
+    });
+    server.registerTool('enrich_subscriber', {
+        description: 'Enrich a subscriber from a connected CRM/ESP provider and merge provider metadata plus company info when available.',
+        inputSchema: {
+            contact_id: z.string().uuid(),
+            provider: z.enum(CONTACT_ENRICHMENT_PROVIDERS).optional(),
+        },
+    }, async ({ contact_id, provider }) => {
+        const projectId = getProjectId();
+        const embedOk = await hasCompaniesEmbed(projectId);
+        const { data: contact, error } = await db()
+            .from('subscribers')
+            .select('id, email, first_name, last_name, company_id, external_id, custom_properties')
+            .eq('project_id', projectId)
+            .eq('id', contact_id)
+            .maybeSingle();
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!contact?.email)
+            return j({ error: 'Subscriber not found', code: 'NOT_FOUND' });
+        const enriched = await enrichContactFromProviders(projectId, contact.email, provider);
+        if (!enriched)
+            return j({ contact, enriched: false, applied_fields: [] });
+        const nextProperties = {
+            ...(contact.custom_properties ?? {}),
+            [enriched.provider]: {
+                ...((contact.custom_properties ?? {})[enriched.provider] ?? {}),
+                ...enriched.properties,
+            },
+        };
+        const companyId = await resolveCompanyId(projectId, {
+            company_name: enriched.companyName ?? undefined,
+            company_domain: enriched.companyDomain ?? undefined,
+        });
+        const { data: updated, error: updateError } = await db()
+            .from('subscribers')
+            .update({
+            first_name: contact.first_name ?? enriched.firstName ?? null,
+            last_name: contact.last_name ?? enriched.lastName ?? null,
+            company_id: companyId ?? contact.company_id ?? null,
+            external_id: contact.external_id ?? enriched.externalId ?? null,
+            custom_properties: nextProperties,
+            updated_at: new Date().toISOString(),
+        })
+            .eq('project_id', projectId)
+            .eq('id', contact_id)
+            .select(embedOk ? '*, company:companies(id, name, domain)' : '*')
+            .single();
+        if (updateError)
+            return txt(`Error: ${updateError.message}`);
+        const appliedFields = [];
+        if (!contact.first_name && enriched.firstName)
+            appliedFields.push('first_name');
+        if (!contact.last_name && enriched.lastName)
+            appliedFields.push('last_name');
+        if (enriched.companyName)
+            appliedFields.push('company');
+        if (!contact.external_id && enriched.externalId)
+            appliedFields.push('external_id');
+        appliedFields.push(`custom_properties.${enriched.provider}`);
+        return j({ contact: updated, enriched: true, provider: enriched.provider, applied_fields: appliedFields });
+    });
+    server.registerTool('subscriber_export', {
+        description: 'Export a contact data portability bundle with contact metadata, email history, and suppression status.',
+        inputSchema: {
+            contactId: z.string().uuid(),
+        },
+    }, async ({ contactId }) => {
+        const result = await exportSubscriberData(getProjectId(), contactId);
+        return j(result);
+    });
+    server.registerTool('set_subscriber_tags', {
+        description: 'Add or remove tags from one or more contacts',
+        inputSchema: {
+            contact_ids: z.array(z.string().uuid()).min(1),
+            add_tags: z.array(z.string()).optional(),
+            remove_tags: z.array(z.string()).optional(),
+        },
+    }, async ({ contact_ids, add_tags = [], remove_tags = [] }) => {
+        if (!add_tags.length && !remove_tags.length)
+            return txt('No tags to add or remove.');
+        const projectId = getProjectId();
+        let updated = 0;
+        for (const cid of contact_ids) {
+            const { data: contact } = await db()
+                .from('subscribers')
+                .select('tags')
+                .eq('id', cid)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (!contact)
+                continue;
+            const currentTags = contact.tags ?? [];
+            const removeSet = new Set(remove_tags);
+            const merged = currentTags.filter((t) => !removeSet.has(t));
+            for (const t of add_tags) {
+                if (!merged.includes(t))
+                    merged.push(t);
+            }
+            const { error } = await db()
+                .from('subscribers')
+                .update({ tags: merged })
+                .eq('id', cid)
+                .eq('project_id', projectId);
+            if (!error)
+                updated++;
+        }
+        return j({ updated, total: contact_ids.length, add_tags, remove_tags });
+    });
+    server.registerTool('estimate_segment_size', {
+        description: 'Estimate how many contacts match filter criteria, with a sample. Useful before creating a segment.',
+        inputSchema: {
+            lifecycle_stage: z.enum(['new', 'active', 'cooling', 'cold', 'churned', 'lead', 'trial', 'customer', 'win-back']).optional(),
+            min_score: z.number().int().min(0).max(100).optional(),
+            max_score: z.number().int().min(0).max(100).optional(),
+            source: z.string().optional(),
+            subscribed_after: z.string().optional().describe('YYYY-MM-DD'),
+            subscribed_before: z.string().optional().describe('YYYY-MM-DD'),
+            has_opened: z.boolean().optional(),
+            has_clicked: z.boolean().optional(),
+            tag: z.string().optional(),
+            company_id: z.string().uuid().optional(),
+            company_domain: z.string().optional(),
+            custom_property: z.string().optional().describe('key=value format'),
+            site_id: z.string().uuid().optional(),
+            sample_size: z.number().int().min(1).max(20).optional().default(5),
+        },
+    }, async (params) => {
+        const projectId = getProjectId();
+        const sampleSize = params.sample_size ?? 5;
+        let q = db()
+            .from('subscribers')
+            .select('id, email, first_name, last_name, engagement_score, lifecycle_stage, source, created_at, last_opened_at, last_clicked_at')
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false);
+        if (params.lifecycle_stage)
+            q = q.eq('lifecycle_stage', params.lifecycle_stage);
+        if (params.min_score !== undefined)
+            q = q.gte('engagement_score', params.min_score);
+        if (params.max_score !== undefined)
+            q = q.lte('engagement_score', params.max_score);
+        if (params.source)
+            q = q.eq('source', params.source);
+        if (params.subscribed_after)
+            q = q.gte('created_at', `${params.subscribed_after}T00:00:00Z`);
+        if (params.subscribed_before)
+            q = q.lte('created_at', `${params.subscribed_before}T23:59:59Z`);
+        if (params.has_opened === true)
+            q = q.not('last_opened_at', 'is', null);
+        if (params.has_opened === false)
+            q = q.is('last_opened_at', null);
+        if (params.has_clicked === true)
+            q = q.not('last_clicked_at', 'is', null);
+        if (params.has_clicked === false)
+            q = q.is('last_clicked_at', null);
+        if (params.tag)
+            q = q.contains('tags', [params.tag]);
+        if (params.company_id)
+            q = q.eq('company_id', params.company_id);
+        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 });
+            }
+        }
+        if (params.site_id) {
+            const { data: subs } = await db()
+                .from('site_subscriptions')
+                .select('contact_id')
+                .eq('site_id', params.site_id)
+                .eq('subscribed', true);
+            const ids = (subs ?? []).map((s) => s.contact_id);
+            if (!ids.length)
+                return j({ total: 0, sample: [] });
+            q = q.in('id', ids);
+        }
+        if (params.company_domain) {
+            const { data: companies } = await db()
+                .from('companies')
+                .select('id')
+                .eq('project_id', projectId)
+                .eq('domain', params.company_domain.trim().toLowerCase());
+            const ids = (companies ?? []).map((company) => company.id);
+            if (!ids.length)
+                return j({ total: 0, sample: [] });
+            q = q.in('company_id', ids);
+        }
+        const { data, error } = await q.order('engagement_score', { ascending: false }).limit(sampleSize);
+        if (error)
+            return txt(`Error: ${error.message}`);
+        // Get full count separately
+        let countQ = db()
+            .from('subscribers')
+            .select('id', { count: 'exact', head: true })
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false);
+        if (params.lifecycle_stage)
+            countQ = countQ.eq('lifecycle_stage', params.lifecycle_stage);
+        if (params.min_score !== undefined)
+            countQ = countQ.gte('engagement_score', params.min_score);
+        if (params.max_score !== undefined)
+            countQ = countQ.lte('engagement_score', params.max_score);
+        if (params.source)
+            countQ = countQ.eq('source', params.source);
+        if (params.subscribed_after)
+            countQ = countQ.gte('created_at', `${params.subscribed_after}T00:00:00Z`);
+        if (params.subscribed_before)
+            countQ = countQ.lte('created_at', `${params.subscribed_before}T23:59:59Z`);
+        if (params.has_opened === true)
+            countQ = countQ.not('last_opened_at', 'is', null);
+        if (params.has_opened === false)
+            countQ = countQ.is('last_opened_at', null);
+        if (params.has_clicked === true)
+            countQ = countQ.not('last_clicked_at', 'is', null);
+        if (params.has_clicked === false)
+            countQ = countQ.is('last_clicked_at', null);
+        if (params.tag)
+            countQ = countQ.contains('tags', [params.tag]);
+        const { count } = await countQ;
+        return j({ total: count ?? (data ?? []).length, sample: data ?? [] });
+    });
+    server.registerTool('identify_inactive', {
+        description: 'Find contacts with no engagement in N days. Dry run by default; set dry_run=false to suppress them.',
+        inputSchema: {
+            days: z.number().int().min(1).optional().default(90).describe('Inactivity threshold in days'),
+            site_id: z.string().uuid().optional(),
+            dry_run: z.boolean().optional().default(true).describe('Preview only (true) or suppress (false)'),
+            limit: z.number().int().min(1).max(200).optional().default(20),
+        },
+    }, async ({ days = 90, site_id, dry_run = true, limit = 20 }) => {
+        const projectId = getProjectId();
+        const sampleLimit = Math.min(limit, 200);
+        const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        let q = db()
+            .from('subscribers')
+            .select('id, email, first_name, last_name, engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_emails_sent')
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false)
+            .or(`last_opened_at.is.null,last_opened_at.lt.${cutoff}`)
+            .or(`last_clicked_at.is.null,last_clicked_at.lt.${cutoff}`);
+        if (site_id) {
+            const { data: subs } = await db()
+                .from('site_subscriptions')
+                .select('contact_id')
+                .eq('site_id', site_id)
+                .eq('subscribed', true);
+            const ids = (subs ?? []).map((s) => s.contact_id);
+            if (!ids.length)
+                return j({ inactive_count: 0, sample: [], message: 'No subscribed contacts for this site.' });
+            q = q.in('id', ids);
+        }
+        const { data: suppressed } = await db()
+            .from('suppressions')
+            .select('email')
+            .eq('project_id', projectId);
+        const suppressedSet = new Set((suppressed ?? []).map((s) => s.email));
+        const { data: contacts, error } = await q.order('engagement_score', { ascending: true }).limit(sampleLimit);
+        if (error)
+            return txt(`Error: ${error.message}`);
+        const inactive = (contacts ?? []).filter((c) => !suppressedSet.has(c.email));
+        if (!dry_run && inactive.length > 0) {
+            const suppressionRows = inactive.map((c) => ({
+                project_id: projectId,
+                email: c.email,
+                reason: 'manual',
+                source: 'inactive_cleanup',
+                details: { days_inactive: days, engagement_score: c.engagement_score },
+            }));
+            const { error: supErr } = await db()
+                .from('suppressions')
+                .upsert(suppressionRows, { onConflict: 'project_id,email', ignoreDuplicates: true });
+            if (supErr)
+                return txt(`Error suppressing: ${supErr.message}`);
+            return j({ suppressed: inactive.length, days_threshold: days, sample: inactive });
+        }
+        return j({
+            inactive_count: inactive.length,
+            days_threshold: days,
+            dry_run: true,
+            already_suppressed: suppressedSet.size,
+            sample: inactive,
+            message: inactive.length > 0
+                ? `Found ${inactive.length} contacts with no engagement in ${days} days. Run with dry_run=false to suppress them.`
+                : `No inactive contacts found (threshold: ${days} days).`,
+        });
+    });
+    server.registerTool('remove_suppression', {
+        description: 'Remove an email address from the suppression list',
+        inputSchema: {
+            email: z.string().email(),
+        },
+    }, async ({ email }) => {
+        const { data, error } = await db()
+            .from('suppressions')
+            .delete()
+            .eq('project_id', getProjectId())
+            .eq('email', email)
+            .select()
+            .single();
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!data)
+            return txt(`No suppression found for ${email}.`);
+        return j({ removed: true, email, previous_reason: data.reason });
+    });
+    server.registerTool('find_duplicates', {
+        description: 'Find duplicate contacts using fuzzy email matching and exact name matching. Returns grouped candidates with confidence scores.',
+        inputSchema: {
+            confidence_threshold: z.number().min(0.5).max(1).optional().describe('Minimum similarity (0.5-1.0, default 0.8)'),
+            limit: z.number().int().min(1).max(200).optional().describe('Max duplicate groups (default 50)'),
+            site_id: z.string().uuid().optional().describe('Filter to contacts subscribed to this site'),
+        },
+    }, async ({ confidence_threshold = 0.8, limit = 50, site_id }) => {
+        const projectId = getProjectId();
+        const maxGroups = Math.min(limit, 200);
+        let q = db()
+            .from('subscribers')
+            .select('id, email, first_name, last_name, engagement_score, lifecycle_stage, created_at, source')
+            .eq('project_id', projectId)
+            .eq('global_unsubscribed', false)
+            .order('created_at', { ascending: true })
+            .limit(2000);
+        if (site_id) {
+            const { data: subs } = await db()
+                .from('site_subscriptions')
+                .select('contact_id')
+                .eq('site_id', site_id)
+                .eq('subscribed', true);
+            const ids = (subs ?? []).map((s) => s.contact_id);
+            if (!ids.length)
+                return j({ duplicate_groups: [], total_groups: 0 });
+            q = q.in('id', ids);
+        }
+        const { data: contacts, error } = await q;
+        if (error)
+            return txt(`Error: ${error.message}`);
+        if (!contacts?.length)
+            return j({ duplicate_groups: [], total_groups: 0 });
+        const lev = (a, b) => {
+            const m = a.length, n = b.length;
+            const dp = Array.from({ length: m + 1 }, (_, i) => i);
+            for (let jj = 1; jj <= n; jj++) {
+                let prev = dp[0];
+                dp[0] = jj;
+                for (let i = 1; i <= m; i++) {
+                    const tmp = dp[i];
+                    dp[i] = a[i - 1] === b[jj - 1] ? prev : 1 + Math.min(prev, dp[i], dp[i - 1]);
+                    prev = tmp;
+                }
+            }
+            return dp[m];
+        };
+        const similarity = (a, b) => {
+            if (a === b)
+                return 1;
+            const maxLen = Math.max(a.length, b.length);
+            if (maxLen === 0)
+                return 1;
+            return 1 - lev(a, b) / maxLen;
+        };
+        const byDomain = {};
+        for (const c of contacts) {
+            const [, domain] = c.email.toLowerCase().split('@');
+            if (!byDomain[domain])
+                byDomain[domain] = [];
+            byDomain[domain].push(c);
+        }
+        const groups = [];
+        const merged = new Set();
+        for (const domain of Object.keys(byDomain)) {
+            const dc = byDomain[domain];
+            for (let i = 0; i < dc.length; i++) {
+                if (merged.has(dc[i].id))
+                    continue;
+                const localA = dc[i].email.split('@')[0].toLowerCase();
+                const group = [dc[i]];
+                for (let jj = i + 1; jj < dc.length; jj++) {
+                    if (merged.has(dc[jj].id))
+                        continue;
+                    const localB = dc[jj].email.split('@')[0].toLowerCase();
+                    const sim = similarity(localA, localB);
+                    if (sim >= confidence_threshold && sim < 1) {
+                        group.push(dc[jj]);
+                        merged.add(dc[jj].id);
+                    }
+                }
+                if (group.length > 1) {
+                    merged.add(dc[i].id);
+                    const avgSim = similarity(group[0].email.split('@')[0].toLowerCase(), group[1].email.split('@')[0].toLowerCase());
+                    groups.push({ group, confidence: Math.round(avgSim * 100) / 100, reason: 'similar_email' });
+                }
+            }
+        }
+        const byName = {};
+        for (const c of contacts) {
+            if (merged.has(c.id))
+                continue;
+            const fn = (c.first_name ?? '').toLowerCase().trim();
+            const ln = (c.last_name ?? '').toLowerCase().trim();
+            if (!fn && !ln)
+                continue;
+            const key = `${fn}|${ln}`;
+            if (!byName[key])
+                byName[key] = [];
+            byName[key].push(c);
+        }
+        for (const nameGroup of Object.values(byName)) {
+            if (nameGroup.length > 1) {
+                groups.push({ group: nameGroup, confidence: 0.7, reason: 'same_name' });
+            }
+        }
+        groups.sort((a, b) => b.confidence - a.confidence);
+        const result = groups.slice(0, maxGroups);
+        return j({ duplicate_groups: result, total_groups: result.length });
+    });
+    server.registerTool('merge_subscribers', {
+        description: 'Merge duplicate contacts into a target. Consolidates subscriptions, enrollments, email history, and consent records. Source contacts are deleted. Requires human approval via dashboard.',
+        inputSchema: {
+            target_id: z.string().uuid().describe('Contact to keep'),
+            source_ids: z.array(z.string().uuid()).min(1).describe('Contacts to merge into target'),
+            approval_id: z.string().uuid().optional().describe('Required — get this by calling once without it, then have a human approve via dashboard.'),
+        },
+    }, async ({ target_id, source_ids, approval_id }) => {
+        // Preview: always show what will happen
+        const { data: target } = await db()
+            .from('subscribers')
+            .select('id, email, first_name, last_name')
+            .eq('id', target_id)
+            .eq('project_id', getProjectId())
+            .maybeSingle();
+        const { data: sources } = await db()
+            .from('subscribers')
+            .select('id, email, first_name, last_name')
+            .in('id', source_ids)
+            .eq('project_id', getProjectId());
+        if (!approval_id) {
+            const approval = await requestApproval('merge_subscribers', {
+                target_id, target_email: target?.email,
+                source_ids, source_count: (sources ?? []).length,
+            });
+            return j({
+                ...approval,
+                preview: { target, sources: sources ?? [] },
+                message: `Will merge ${(sources ?? []).length} contact(s) into ${target?.email ?? target_id}. Source contacts will be deleted. Requires human approval.`,
+            });
+        }
+        const check = await checkApproval(approval_id, { consume: true });
+        if (!check.approved) {
+            return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
+        }
+        const { data, error } = await db().rpc('merge_subscribers', {
+            p_project_id: getProjectId(),
+            p_target_id: target_id,
+            p_source_ids: source_ids,
+        });
+        if (error)
+            return txt(`Error: ${error.message}`);
+        logAudit({ action: 'contacts.merged', resourceType: 'contact', resourceId: target_id, details: { source_ids, result: data } });
+        return j(data);
+    });
+    server.registerTool('get_contact_schema', {
+        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.',
+        inputSchema: {
+            site_id: z.string().uuid().describe('Site to inspect — only contacts belonging to this site are sampled'),
+        },
+    }, async ({ site_id }) => {
+        const projectId = getProjectId();
+        // Sample recent contacts to discover keys (LIMIT 500 is enough for schema discovery)
+        const { data, error } = await db().rpc('get_contact_schema_keys', {
+            p_project_id: projectId,
+            p_site_id: site_id,
+        });
+        if (error) {
+            // Fallback: inline query if RPC not yet available
+            const { data: rows, error: qErr } = await db()
+                .from('subscribers')
+                .select('custom_properties')
+                .eq('project_id', projectId)
+                .eq('source_site', site_id)
+                .not('custom_properties', 'is', null)
+                .order('created_at', { ascending: false })
+                .limit(500);
+            if (qErr)
+                return txt(`Error: ${qErr.message}`);
+            const keyMap = new Map();
+            for (const row of rows ?? []) {
+                const props = row.custom_properties;
+                if (!props)
+                    continue;
+                for (const [k, v] of Object.entries(props)) {
+                    if (!keyMap.has(k))
+                        keyMap.set(k, { values: new Set(), count: 0 });
+                    const entry = keyMap.get(k);
+                    entry.count++;
+                    if (v !== null && v !== undefined && entry.values.size < 3) {
+                        entry.values.add(String(v));
+                    }
+                }
+            }
+            const schema = Array.from(keyMap.entries())
+                .sort((a, b) => b[1].count - a[1].count)
+                .map(([key, { values, count }]) => ({
+                key,
+                merge_tag: `{{custom.${key}}}`,
+                merge_tag_with_fallback: `{{custom.${key}|fallback}}`,
+                example_values: Array.from(values),
+                contacts_with_this_key: count,
+            }));
+            return j({
+                site_id,
+                total_keys: schema.length,
+                schema,
+                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).',
+            });
+        }
+        return j({
+            site_id,
+            total_keys: data.length,
+            schema: data.map(r => ({
+                key: r.key,
+                merge_tag: `{{custom.${r.key}}}`,
+                merge_tag_with_fallback: `{{custom.${r.key}|fallback}}`,
+                example_values: r.examples ?? [],
+                contacts_with_this_key: r.count,
+            })),
+            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).',
+        });
+    });
+}