@sendinel/mcp-server 1.0.139 → 1.0.141

package/build/tools/contacts.js

@@ -1,3 +1,4 @@
+import { dbErrorResult } from '../lib/db-errors.js';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
 import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
@@ -6,6 +7,8 @@ import { z } from 'zod';
 import { callSendinelV1 } from '../lib/v1-client.js';
 import { db, projectClientForWriteback } from '../db.js';
 import { getProjectId } from '../project.js';
+import { dbToolError, toolError } from '../lib/db-error.js';
+import { resolveSegmentContactIds } from '../lib/send-audience.js';
 import { checkPlanLimit, contactLimitMessage } from '../plan-limits.js';
 import { logConsent, logAudit } from '../audit.js';
 import { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval, withApproval } from '../lib/action-approvals.js';
@@ -237,6 +240,49 @@ function normalizePhoneE164(value) {
 function isPlainObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+const SUBSCRIBER_VIEW_COLUMNS = new Set([
+    'contact', 'status_strip', 'quick_send', 'site', 'company', 'status', 'last_activity',
+    'sms_opt_in', 'tags', 'score', 'stage', 'opens', 'clicks', 'joined', 'embed_actions',
+    'email', 'first_name', 'last_name', 'introduced_by',
+]);
+const SUBSCRIBER_VIEW_STAGES = new Set(['new', 'active', 'cooling', 'cold', 'churned', 'lead', 'trial', 'customer', 'win-back']);
+function validateSubscriberViewInput(columns, filters) {
+    if (isPlainObject(filters)) {
+        for (const [key, value] of Object.entries(filters)) {
+            if (!SUBSCRIBER_VIEW_FILTER_KEYS.has(key))
+                return `Unknown filter "${key}". Valid keys: ${[...SUBSCRIBER_VIEW_FILTER_KEYS].join(', ')}`;
+            if (key === 'show_test' ? typeof value !== 'boolean' : typeof value !== 'string' || value.length > 500)
+                return `Invalid value for filter "${key}"`;
+            if (key === 'stage' && value !== '' && !SUBSCRIBER_VIEW_STAGES.has(value))
+                return `Invalid stage. Valid stages: ${[...SUBSCRIBER_VIEW_STAGES].join(', ')}`;
+            if (key === 'dir' && value !== 'asc' && value !== 'desc')
+                return 'dir must be asc or desc';
+            if (key === 'sort' && value !== '' && !SUBSCRIBER_VIEW_SORT_FIELDS.has(value))
+                return 'Invalid sort field';
+            if (key === 'status' && !['', 'all', 'active', 'unsubscribed', 'not_subscribed'].includes(value))
+                return 'Invalid subscription status';
+            if (key === 'cp_key' && value !== '' && !SUBSCRIBER_VIEW_CUSTOM_PROPERTY_KEY_RE.test(value))
+                return 'Invalid custom property key';
+        }
+    }
+    if (isPlainObject(filters) && Boolean(filters.cp_key) !== Boolean(filters.cp_value))
+        return 'cp_key and cp_value must be provided together';
+    if (isPlainObject(columns)) {
+        for (const list of [columns.order, columns.hidden]) {
+            if (list === undefined)
+                continue;
+            if (!Array.isArray(list) || list.length > SUBSCRIBER_VIEW_MAX_COLUMNS)
+                return 'Invalid column list';
+            for (const key of list) {
+                if (typeof key !== 'string' || !SUBSCRIBER_VIEW_KEY_RE.test(key) ||
+                    (!SUBSCRIBER_VIEW_COLUMNS.has(key) && !(key.startsWith('prop:') && SUBSCRIBER_VIEW_CUSTOM_PROPERTY_KEY_RE.test(key.slice(5))))) {
+                    return `Unknown column "${String(key)}". Use a subscriber column or prop:<custom property key>`;
+                }
+            }
+        }
+    }
+    return null;
+}
 function normalizeSubscriberViewKeys(value) {
     if (!Array.isArray(value))
         return [];
@@ -1074,9 +1120,12 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             filters: z.record(z.string(), z.unknown()).optional(),
         },
     }, async ({ name, view_mode, columns, filters }) => {
+        const inputError = validateSubscriberViewInput(columns, filters);
+        if (inputError)
+            return toolError({ error: inputError, code: 'validation_failed' });
         const normalizedName = name.trim().slice(0, SUBSCRIBER_VIEW_MAX_NAME_LENGTH);
         if (!normalizedName)
-            return txt('Error: name is required');
+            return toolError({ error: 'name is required', code: 'validation_failed' });
         const { data, error } = await db()
             .from('subscriber_list_views')
             .insert({
@@ -1090,9 +1139,10 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .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`);
+            return toolError({ error: `A view named "${normalizedName}" already exists`, code: 'conflict' });
         if (error)
-            return txt(`Error: ${error.message}`);
+            return toolError(dbToolError(error));
+        await logAudit({ action: 'subscriber_view.saved', resourceType: 'subscriber_view', resourceId: data?.id });
         return j({ view: data });
     });
     server.registerTool('update_subscriber_view', {
@@ -1115,11 +1165,14 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         if (name === undefined && view_mode === undefined && columns === undefined && filters === undefined) {
             return txt('Nothing to update');
         }
+        const inputError = validateSubscriberViewInput(columns, filters);
+        if (inputError)
+            return toolError({ error: inputError, code: 'validation_failed' });
         const updates = {};
         if (name !== undefined) {
             const normalizedName = name.trim().slice(0, SUBSCRIBER_VIEW_MAX_NAME_LENGTH);
             if (!normalizedName)
-                return txt('Error: name is required');
+                return toolError({ error: 'name is required', code: 'validation_failed' });
             updates.name = normalizedName;
         }
         if (view_mode !== undefined)
@@ -1136,11 +1189,12 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             .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');
+            return toolError({ error: 'A view with that name already exists', code: 'conflict' });
         if (error)
-            return txt(`Error: ${error.message}`);
+            return toolError(dbToolError(error));
         if (!data)
-            return txt('View not found');
+            return toolError({ error: 'View not found', code: 'not_found' });
+        await logAudit({ action: 'subscriber_view.saved', resourceType: 'subscriber_view', resourceId: data?.id });
         return j({ view: data });
     });
     server.registerTool('delete_subscriber_view', {
@@ -1253,133 +1307,138 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             utm_term: z.string().optional(),
         },
     }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
-        email = email.trim().toLowerCase();
-        const projectId = getProjectId();
-        // Block distribution list / system addresses
-        const DISTRO_LOCAL_PARTS = new Set(['all', 'everyone', 'distro', 'broadcast', 'announce', 'postmaster', 'abuse', 'mailer-daemon', 'bounce', 'bounces', 'noreply', 'no-reply', 'nobody', 'null', 'void']);
-        const DISTRO_PATTERNS = [/^all[-+.]/, /[-+.]all$/, /^list[-+.]/, /[-+.]list$/, /[-+.]announce$/, /^announce[-+.]/, /[-+.]distro$/, /^distro[-+.]/, /[-+.]broadcast$/, /^broadcast[-+.]/];
-        const local = email.trim().toLowerCase().split('@')[0] ?? '';
-        if (DISTRO_LOCAL_PARTS.has(local) || DISTRO_PATTERNS.some(p => p.test(local))) {
-            return contactInputError('validation_failed', `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.`);
-        }
-        // Validate project ownership before the cap, and reuse the double opt-in lookup.
-        const { data: siteInfo, error: siteError } = await db().from('sites')
-            .select('double_opt_in').eq('id', site_id).eq('project_id', projectId).maybeSingle();
-        if (siteError)
-            throw new Error(`Site lookup failed: ${siteError.message}`);
-        if (!siteInfo)
-            return contactInputError('not_found', 'Site not found for this project.');
-        const needsConfirm = siteInfo.double_opt_in === true;
-        const limit = await checkPlanLimit('contacts');
-        if (!limit.allowed) {
-            return contactInputError('plan_limit', contactLimitMessage(limit));
-        }
-        const embedOk = await hasCompaniesEmbed(projectId);
-        const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
-        let { data: existingContact, error: lookupError } = await db()
-            .from('subscribers')
-            .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
-            .eq('project_id', projectId)
-            .eq('email', email)
-            .maybeSingle();
-        if (lookupError)
-            return txt(`Error looking up contact: ${lookupError.message}`);
-        let customProperties;
-        if (company_name || company_domain) {
-            const orgId = await getProjectOrgId(projectId);
-            customProperties = await normalizeMcpContactPropertyPatch({
-                ...(company_name ? { company_name } : {}),
-                ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
-            }, { orgId, projectId });
-        }
-        const selection = embedOk ? '*, company:companies(id, name, domain)' : '*';
-        let contact;
-        if (!existingContact) {
-            const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
-            if (customProperties)
-                row.custom_properties = customProperties;
-            if (!needsConfirm)
-                row.opted_in_at = new Date().toISOString();
-            if (utm_source)
-                row.utm_source = utm_source;
-            if (utm_medium)
-                row.utm_medium = utm_medium;
-            if (utm_campaign)
-                row.utm_campaign = utm_campaign;
-            if (utm_content)
-                row.utm_content = utm_content;
-            if (utm_term)
-                row.utm_term = utm_term;
-            const { data, error } = await db().from('subscribers')
-                .upsert(row, { onConflict: 'project_id,email', ignoreDuplicates: true })
-                .select(selection).maybeSingle();
-            if (error)
-                return txt(`Error creating contact: ${error.message}`);
-            contact = data;
-            if (!contact) {
-                // A concurrent add won the unique key; its provenance belongs to that insert.
-                const result = await db().from('subscribers')
-                    .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
-                    .eq('project_id', projectId).eq('email', email).single();
-                if (result.error)
-                    return txt(`Error looking up contact: ${result.error.message}`);
-                existingContact = result.data;
+        try {
+            email = email.trim().toLowerCase();
+            const projectId = getProjectId();
+            // Block distribution list / system addresses
+            const DISTRO_LOCAL_PARTS = new Set(['all', 'everyone', 'distro', 'broadcast', 'announce', 'postmaster', 'abuse', 'mailer-daemon', 'bounce', 'bounces', 'noreply', 'no-reply', 'nobody', 'null', 'void']);
+            const DISTRO_PATTERNS = [/^all[-+.]/, /[-+.]all$/, /^list[-+.]/, /[-+.]list$/, /[-+.]announce$/, /^announce[-+.]/, /[-+.]distro$/, /^distro[-+.]/, /[-+.]broadcast$/, /^broadcast[-+.]/];
+            const local = email.trim().toLowerCase().split('@')[0] ?? '';
+            if (DISTRO_LOCAL_PARTS.has(local) || DISTRO_PATTERNS.some(p => p.test(local))) {
+                return contactInputError('validation_failed', `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.`);
             }
-        }
-        const existing = !!existingContact;
-        if (existingContact) {
-            const empty = (value) => value == null || value === '';
-            const row = {};
-            for (const [key, value] of Object.entries({ first_name, last_name, company_id: resolvedCompanyId })) {
-                if (empty(existingContact[key]) && !empty(value))
-                    row[key] = value;
+            // Validate project ownership before the cap, and reuse the double opt-in lookup.
+            const { data: siteInfo, error: siteError } = await db().from('sites')
+                .select('double_opt_in').eq('id', site_id).eq('project_id', projectId).maybeSingle();
+            if (siteError)
+                return dbErrorResult(siteError);
+            if (!siteInfo)
+                return contactInputError('not_found', 'Site not found for this project.');
+            const needsConfirm = siteInfo.double_opt_in === true;
+            const limit = await checkPlanLimit('contacts');
+            if (!limit.allowed) {
+                return contactInputError('plan_limit', contactLimitMessage(limit));
             }
-            if (!needsConfirm && existingContact.opted_in_at == null)
-                row.opted_in_at = new Date().toISOString();
-            const missingProperties = Object.fromEntries(Object.entries(customProperties ?? {})
-                .filter(([key]) => !Object.hasOwn(existingContact.custom_properties ?? {}, key)));
-            if (Object.keys(missingProperties).length) {
-                row.custom_properties = { ...(existingContact.custom_properties ?? {}), ...missingProperties };
+            const embedOk = await hasCompaniesEmbed(projectId);
+            const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
+            let { data: existingContact, error: lookupError } = await db()
+                .from('subscribers')
+                .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
+                .eq('project_id', projectId)
+                .eq('email', email)
+                .maybeSingle();
+            if (lookupError)
+                return dbErrorResult(lookupError);
+            let customProperties;
+            if (company_name || company_domain) {
+                const orgId = await getProjectOrgId(projectId);
+                customProperties = await normalizeMcpContactPropertyPatch({
+                    ...(company_name ? { company_name } : {}),
+                    ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
+                }, { orgId, projectId });
             }
-            if (Object.keys(row).length) {
-                let update = db().from('subscribers').update(row)
-                    .eq('id', existingContact.id).eq('project_id', projectId);
-                // The stored values must still match: a concurrent edit always wins over a re-add.
-                for (const key of Object.keys(row)) {
-                    const previous = existingContact[key];
-                    update = previous == null ? update.is(key, null)
-                        : update.eq(key, key === 'custom_properties' ? JSON.stringify(previous) : previous);
-                }
-                const { error } = await update;
+            const selection = embedOk ? '*, company:companies(id, name, domain)' : '*';
+            let contact;
+            if (!existingContact) {
+                const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
+                if (customProperties)
+                    row.custom_properties = customProperties;
+                if (!needsConfirm)
+                    row.opted_in_at = new Date().toISOString();
+                if (utm_source)
+                    row.utm_source = utm_source;
+                if (utm_medium)
+                    row.utm_medium = utm_medium;
+                if (utm_campaign)
+                    row.utm_campaign = utm_campaign;
+                if (utm_content)
+                    row.utm_content = utm_content;
+                if (utm_term)
+                    row.utm_term = utm_term;
+                const { data, error } = await db().from('subscribers')
+                    .upsert(row, { onConflict: 'project_id,email', ignoreDuplicates: true })
+                    .select(selection).maybeSingle();
                 if (error)
-                    return txt(`Error updating contact: ${error.message}`);
+                    return dbErrorResult(error);
+                contact = data;
+                if (!contact) {
+                    // A concurrent add won the unique key; its provenance belongs to that insert.
+                    const result = await db().from('subscribers')
+                        .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
+                        .eq('project_id', projectId).eq('email', email).single();
+                    if (result.error)
+                        return dbErrorResult(result.error);
+                    existingContact = result.data;
+                }
+            }
+            const existing = !!existingContact;
+            if (existingContact) {
+                const empty = (value) => value == null || value === '';
+                const row = {};
+                for (const [key, value] of Object.entries({ first_name, last_name, company_id: resolvedCompanyId })) {
+                    if (empty(existingContact[key]) && !empty(value))
+                        row[key] = value;
+                }
+                if (!needsConfirm && existingContact.opted_in_at == null)
+                    row.opted_in_at = new Date().toISOString();
+                const missingProperties = Object.fromEntries(Object.entries(customProperties ?? {})
+                    .filter(([key]) => !Object.hasOwn(existingContact.custom_properties ?? {}, key)));
+                if (Object.keys(missingProperties).length) {
+                    row.custom_properties = { ...(existingContact.custom_properties ?? {}), ...missingProperties };
+                }
+                if (Object.keys(row).length) {
+                    let update = db().from('subscribers').update(row)
+                        .eq('id', existingContact.id).eq('project_id', projectId);
+                    // The stored values must still match: a concurrent edit always wins over a re-add.
+                    for (const key of Object.keys(row)) {
+                        const previous = existingContact[key];
+                        update = previous == null ? update.is(key, null)
+                            : update.eq(key, key === 'custom_properties' ? JSON.stringify(previous) : previous);
+                    }
+                    const { error } = await update;
+                    if (error)
+                        return dbErrorResult(error);
+                }
+                const result = await db().from('subscribers').select(selection)
+                    .eq('id', existingContact.id).eq('project_id', projectId).single();
+                if (result.error)
+                    return dbErrorResult(result.error);
+                contact = result.data;
+            }
+            const existingMessage = existing ? { message: 'Contact already existed; source and existing fields were not changed.' } : {};
+            const { error: subErr } = await db()
+                .from('site_subscriptions')
+                .upsert({ contact_id: contact.id, site_id, subscribed: !needsConfirm }, { onConflict: 'contact_id,site_id' });
+            if (subErr)
+                return dbErrorResult(subErr);
+            if (existing)
+                logAudit({ action: 'contact.readded', resourceType: 'contact', resourceId: contact.id, details: { email, requested_source: source, existing: true } });
+            if (needsConfirm) {
+                // Create opt-in token (confirmation email must be sent externally in MCP context)
+                await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
+                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
+                logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
+                return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
             }
-            const result = await db().from('subscribers').select(selection)
-                .eq('id', existingContact.id).eq('project_id', projectId).single();
-            if (result.error)
-                return txt(`Error reading contact: ${result.error.message}`);
-            contact = result.data;
-        }
-        const existingMessage = existing ? { message: 'Contact already existed; source and existing fields were not changed.' } : {};
-        const { error: subErr } = await db()
-            .from('site_subscriptions')
-            .upsert({ contact_id: contact.id, site_id, subscribed: !needsConfirm }, { onConflict: 'contact_id,site_id' });
-        if (subErr)
-            return { content: [{ type: 'text', text: `Contact created but subscription failed: ${subErr.message}` }] };
-        if (existing)
-            logAudit({ action: 'contact.readded', resourceType: 'contact', resourceId: contact.id, details: { email, requested_source: source, existing: true } });
-        if (needsConfirm) {
-            // Create opt-in token (confirmation email must be sent externally in MCP context)
-            await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
             await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
-            logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
-            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
-        }
-        await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
-        logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
-        if (!existing)
-            logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
-        return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
+            logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
+            if (!existing)
+                logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
+            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
+        }
+        catch (error) {
+            return dbErrorResult(error);
+        }
     });
     server.registerTool('import_subscribers', {
         title: 'Import Subscribers',
@@ -1643,6 +1702,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         },
         description: 'List contacts filtered by engagement score range and/or lifecycle stage. Useful for building re-engagement campaigns or identifying high-value contacts.',
         inputSchema: {
+            segment_id: z.string().uuid().optional().describe('Saved segment; mutually exclusive with inline audience filters'),
             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(),
@@ -1651,8 +1711,28 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             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 }) => {
+    }, async ({ segment_id, lifecycle_stage, min_score, max_score, site_id, company_id, company_domain, limit }) => {
         const projectId = getProjectId();
+        let segmentIds;
+        if (segment_id) {
+            if ([lifecycle_stage, min_score, max_score, site_id, company_id, company_domain].some(value => value !== undefined)) {
+                return toolError({ error: 'Provide segment_id or inline filters, not both', code: 'validation_failed' });
+            }
+            const { data: segment, error } = await db().from('segments').select('rules')
+                .eq('project_id', projectId).eq('id', segment_id).maybeSingle();
+            if (error)
+                return toolError(dbToolError(error));
+            if (!segment)
+                return toolError({ error: 'Segment not found', code: 'not_found' });
+            try {
+                segmentIds = await resolveSegmentContactIds(projectId, segment.rules);
+            }
+            catch (error) {
+                return toolError(isSegmentRulesError(error) ? { error: error.message, code: 'validation_failed' } : { error: 'Unable to evaluate segment', code: 'internal_error' });
+            }
+            if (!segmentIds.length)
+                return j([]);
+        }
         const embedOk = await hasCompaniesEmbed(projectId);
         let q = db()
             .from('subscribers')
@@ -1691,9 +1771,23 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 return { content: [{ type: 'text', text: '[]' }] };
             q = q.in('company_id', ids);
         }
+        if (segmentIds) {
+            const rows = [];
+            for (const ids of chunkIds(segmentIds)) {
+                // A Supabase builder is mutable; build a fresh query for each chunk.
+                const { data, error } = await db().from('subscribers')
+                    .select(embedOk ? SEGMENT_SUBSCRIBER_SELECT_WITH_COMPANY : SEGMENT_SUBSCRIBER_SELECT_NO_COMPANY)
+                    .eq('project_id', projectId).eq('global_unsubscribed', false).in('id', ids)
+                    .order('engagement_score', { ascending: false }).limit(limit ?? 50);
+                if (error)
+                    return toolError(dbToolError(error));
+                rows.push(...(data ?? []));
+            }
+            return j(rows.sort((a, b) => b.engagement_score - a.engagement_score).slice(0, limit ?? 50));
+        }
         const { data, error } = await q;
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return toolError(dbToolError(error));
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('update_subscriber', {
@@ -1719,194 +1813,199 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             timezone: z.string().nullable().optional().describe('IANA time zone identifier, e.g. America/Los_Angeles'),
         },
     }, async ({ contact_id, email, first_name, last_name, company_id, company_name, company_domain, tags, custom_properties, phone_e164, timezone }) => {
-        const projectId = getProjectId();
-        let propertyWarnings = [];
-        let fields;
-        if (custom_properties !== undefined) {
-            let definitions;
-            try {
-                definitions = await registeredCustomFields(projectId);
-            }
-            catch {
-                return j({ error: 'Custom field definitions unavailable; update not performed', code: 'INTERNAL_ERROR' });
-            }
-            fields = Object.fromEntries(definitions.map(field => [field.key, field]));
-            const values = Object.fromEntries(Object.entries(custom_properties).filter(([, value]) => value !== null));
-            const invalidShape = Object.entries(values).find(([key, value]) => {
-                if (!Object.hasOwn(fields, key))
-                    return false;
-                const type = fields[key].type;
-                if (type === 'multi_select')
-                    return typeof value !== 'string' && (!Array.isArray(value) || value.some(item => typeof item !== 'string'));
-                return typeof value === 'object' && type !== 'contact_reference';
-            });
-            const { anomalies } = normalizeContactProperties(values, { fields });
-            if (invalidShape || anomalies.length) {
-                const key = invalidShape?.[0] ?? anomalies[0].key;
-                return contactInputError('validation_failed', `custom_properties.${key} does not match its registered ${fields[key].type} definition or options`);
-            }
-            propertyWarnings = unknownCustomPropertyWarnings(custom_properties, fields);
-        }
-        const embedOk = await hasCompaniesEmbed(projectId);
-        const updates = {};
-        let customPropertyChanges = [];
-        if (email !== undefined)
-            updates.email = email;
-        if (first_name !== undefined)
-            updates.first_name = first_name;
-        if (last_name !== undefined)
-            updates.last_name = last_name;
-        if (company_id !== undefined) {
-            updates.company_id = company_id;
-        }
-        else if (company_name || company_domain) {
-            updates.company_id = await resolveCompanyId(projectId, {
-                company_name: company_name ?? undefined,
-                company_domain: company_domain ?? undefined,
-            });
-        }
-        if (tags !== undefined)
-            updates.tags = tags;
-        if (custom_properties !== undefined) {
-            const { data: existing, error: existingError } = await db()
-                .from('subscribers')
-                .select('custom_properties')
-                .eq('id', contact_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            if (existingError)
-                return j({ error: 'Contact properties unavailable; update not performed', code: 'INTERNAL_ERROR' });
-            if (!existing)
-                return contactInputError('not_found', 'Contact not found');
-            const orgId = await getProjectOrgId(projectId);
-            const normalizedPatch = await normalizeMcpContactPropertyPatch(custom_properties, {
-                orgId,
-                projectId,
-                subscriberId: contact_id,
-                preserveNullDeletions: true,
-                fields,
-            });
-            customPropertyChanges = diffCustomProperties(existing?.custom_properties ?? null, normalizedPatch);
-            updates.custom_properties = {
-                ...(existing?.custom_properties ?? {}),
-                ...normalizedPatch,
-                ...(company_name ? { company_name } : {}),
-                ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
-            };
-            for (const [key, value] of Object.entries(normalizedPatch)) {
-                if (value === null)
-                    delete updates.custom_properties[key];
-            }
-        }
-        else if (company_name || company_domain) {
-            const { data: existing } = await db()
-                .from('subscribers')
-                .select('custom_properties')
-                .eq('id', contact_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            const orgId = await getProjectOrgId(projectId);
-            const companyPatch = await normalizeMcpContactPropertyPatch({
-                ...(company_name ? { company_name } : {}),
-                ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
-            }, { orgId, projectId, subscriberId: contact_id });
-            updates.custom_properties = {
-                ...(existing?.custom_properties ?? {}),
-                ...companyPatch,
-            };
-        }
-        if (phone_e164 !== undefined) {
-            if (phone_e164 === null) {
-                updates.phone_e164 = null;
-            }
-            else {
-                const normalized = normalizePhoneE164(phone_e164);
-                if (!normalized)
-                    return contactInputError('validation_failed', 'Invalid phone_e164: must be a valid E.164 phone number (SMS is US-only for now).');
-                updates.phone_e164 = normalized;
-            }
-        }
-        if (timezone !== undefined) {
-            if (timezone === null) {
-                updates.timezone = null;
-            }
-            else {
-                // Region form only; mirrors normalizeTimezoneField in the dashboard. Intl accepts UTC offsets
-                // ("+05:00") and abbreviations ("EST"), which Postgres AT TIME ZONE reads differently.
-                if (timezone !== 'UTC' && !/^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)+$/.test(timezone)) {
-                    return contactInputError('validation_failed', 'Invalid timezone: must be an IANA region name such as America/Los_Angeles (not a UTC offset or abbreviation).');
-                }
+        try {
+            const projectId = getProjectId();
+            let propertyWarnings = [];
+            let fields;
+            if (custom_properties !== undefined) {
+                let definitions;
                 try {
-                    new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+                    definitions = await registeredCustomFields(projectId);
                 }
                 catch {
-                    return contactInputError('validation_failed', 'Invalid timezone: must be a valid IANA time zone identifier.');
+                    return j({ error: 'Custom field definitions unavailable; update not performed', code: 'INTERNAL_ERROR' });
                 }
-                updates.timezone = timezone;
+                fields = Object.fromEntries(definitions.map(field => [field.key, field]));
+                const values = Object.fromEntries(Object.entries(custom_properties).filter(([, value]) => value !== null));
+                const invalidShape = Object.entries(values).find(([key, value]) => {
+                    if (!Object.hasOwn(fields, key))
+                        return false;
+                    const type = fields[key].type;
+                    if (type === 'multi_select')
+                        return typeof value !== 'string' && (!Array.isArray(value) || value.some(item => typeof item !== 'string'));
+                    return typeof value === 'object' && type !== 'contact_reference';
+                });
+                const { anomalies } = normalizeContactProperties(values, { fields });
+                if (invalidShape || anomalies.length) {
+                    const key = invalidShape?.[0] ?? anomalies[0].key;
+                    return contactInputError('validation_failed', `custom_properties.${key} does not match its registered ${fields[key].type} definition or options`);
+                }
+                propertyWarnings = unknownCustomPropertyWarnings(custom_properties, fields);
             }
-        }
-        if (!Object.keys(updates).length)
-            return contactInputError('validation_failed', 'No fields to update.');
-        const tagResult = {};
-        if (tags !== undefined) {
-            let previousTags;
-            try {
-                const { data: existing, error: readError } = await db()
+            const embedOk = await hasCompaniesEmbed(projectId);
+            const updates = {};
+            let customPropertyChanges = [];
+            if (email !== undefined)
+                updates.email = email;
+            if (first_name !== undefined)
+                updates.first_name = first_name;
+            if (last_name !== undefined)
+                updates.last_name = last_name;
+            if (company_id !== undefined) {
+                updates.company_id = company_id;
+            }
+            else if (company_name || company_domain) {
+                updates.company_id = await resolveCompanyId(projectId, {
+                    company_name: company_name ?? undefined,
+                    company_domain: company_domain ?? undefined,
+                });
+            }
+            if (tags !== undefined)
+                updates.tags = tags;
+            if (custom_properties !== undefined) {
+                const { data: existing, error: existingError } = await db()
                     .from('subscribers')
-                    .select('tags')
+                    .select('custom_properties')
                     .eq('id', contact_id)
                     .eq('project_id', projectId)
                     .maybeSingle();
-                if (!readError && Array.isArray(existing?.tags) && existing.tags.every((tag) => typeof tag === 'string')) {
-                    previousTags = existing.tags;
+                if (existingError)
+                    return j({ error: 'Contact properties unavailable; update not performed', code: 'INTERNAL_ERROR' });
+                if (!existing)
+                    return contactInputError('not_found', 'Contact not found');
+                const orgId = await getProjectOrgId(projectId);
+                const normalizedPatch = await normalizeMcpContactPropertyPatch(custom_properties, {
+                    orgId,
+                    projectId,
+                    subscriberId: contact_id,
+                    preserveNullDeletions: true,
+                    fields,
+                });
+                customPropertyChanges = diffCustomProperties(existing?.custom_properties ?? null, normalizedPatch);
+                updates.custom_properties = {
+                    ...(existing?.custom_properties ?? {}),
+                    ...normalizedPatch,
+                    ...(company_name ? { company_name } : {}),
+                    ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
+                };
+                for (const [key, value] of Object.entries(normalizedPatch)) {
+                    if (value === null)
+                        delete updates.custom_properties[key];
                 }
             }
-            catch {
-                // The replacement can still succeed, but the previous set is unknown.
+            else if (company_name || company_domain) {
+                const { data: existing } = await db()
+                    .from('subscribers')
+                    .select('custom_properties')
+                    .eq('id', contact_id)
+                    .eq('project_id', projectId)
+                    .maybeSingle();
+                const orgId = await getProjectOrgId(projectId);
+                const companyPatch = await normalizeMcpContactPropertyPatch({
+                    ...(company_name ? { company_name } : {}),
+                    ...(company_domain ? { company_domain: normalizeCompanyDomain(company_domain) } : {}),
+                }, { orgId, projectId, subscriberId: contact_id });
+                updates.custom_properties = {
+                    ...(existing?.custom_properties ?? {}),
+                    ...companyPatch,
+                };
             }
-            if (previousTags === undefined) {
-                tagResult.warnings = ['Tags were REPLACED, but previous tags could not be read; removed and added tags are unknown. Use set_subscriber_tags to add tags without replacing the whole set.'];
+            if (phone_e164 !== undefined) {
+                if (phone_e164 === null) {
+                    updates.phone_e164 = null;
+                }
+                else {
+                    const normalized = normalizePhoneE164(phone_e164);
+                    if (!normalized)
+                        return contactInputError('validation_failed', 'Invalid phone_e164: must be a valid E.164 phone number (SMS is US-only for now).');
+                    updates.phone_e164 = normalized;
+                }
             }
-            else {
-                const previousSet = new Set(previousTags);
-                const nextSet = new Set(tags);
-                tagResult.tags_removed = [...previousSet].filter((tag) => !nextSet.has(tag));
-                tagResult.tags_added = [...nextSet].filter((tag) => !previousSet.has(tag));
-                if (tagResult.tags_removed.length > 0) {
-                    tagResult.warnings = ['Tags were REPLACED. Use set_subscriber_tags to add tags without replacing the whole set.'];
+            if (timezone !== undefined) {
+                if (timezone === null) {
+                    updates.timezone = null;
+                }
+                else {
+                    // Region form only; mirrors normalizeTimezoneField in the dashboard. Intl accepts UTC offsets
+                    // ("+05:00") and abbreviations ("EST"), which Postgres AT TIME ZONE reads differently.
+                    if (timezone !== 'UTC' && !/^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)+$/.test(timezone)) {
+                        return contactInputError('validation_failed', 'Invalid timezone: must be an IANA region name such as America/Los_Angeles (not a UTC offset or abbreviation).');
+                    }
+                    try {
+                        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+                    }
+                    catch {
+                        return contactInputError('validation_failed', 'Invalid timezone: must be a valid IANA time zone identifier.');
+                    }
+                    updates.timezone = timezone;
                 }
             }
-        }
-        updates.updated_at = new Date().toISOString();
-        const { data, error } = await db()
-            .from('subscribers')
-            .update(updates)
-            .eq('id', contact_id)
-            .eq('project_id', projectId)
-            .select(embedOk ? UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY : UPDATE_SUBSCRIBER_SELECT_NO_COMPANY)
-            .single();
-        if (error?.code === '23505' && updates.phone_e164 !== undefined) {
-            return contactInputError('conflict', 'Another contact in this project already has this phone number.');
-        }
-        if (error)
-            return j({ error: `Error: ${error.message}`, code: 'INTERNAL_ERROR' });
-        if (customPropertyChanges.length > 0) {
-            logAudit({
-                action: 'contact.custom_properties_changed',
-                resourceType: 'contact',
-                resourceId: contact_id,
-                details: { changes: customPropertyChanges },
+            if (!Object.keys(updates).length)
+                return contactInputError('validation_failed', 'No fields to update.');
+            const tagResult = {};
+            if (tags !== undefined) {
+                let previousTags;
+                try {
+                    const { data: existing, error: readError } = await db()
+                        .from('subscribers')
+                        .select('tags')
+                        .eq('id', contact_id)
+                        .eq('project_id', projectId)
+                        .maybeSingle();
+                    if (!readError && Array.isArray(existing?.tags) && existing.tags.every((tag) => typeof tag === 'string')) {
+                        previousTags = existing.tags;
+                    }
+                }
+                catch {
+                    // The replacement can still succeed, but the previous set is unknown.
+                }
+                if (previousTags === undefined) {
+                    tagResult.warnings = ['Tags were REPLACED, but previous tags could not be read; removed and added tags are unknown. Use set_subscriber_tags to add tags without replacing the whole set.'];
+                }
+                else {
+                    const previousSet = new Set(previousTags);
+                    const nextSet = new Set(tags);
+                    tagResult.tags_removed = [...previousSet].filter((tag) => !nextSet.has(tag));
+                    tagResult.tags_added = [...nextSet].filter((tag) => !previousSet.has(tag));
+                    if (tagResult.tags_removed.length > 0) {
+                        tagResult.warnings = ['Tags were REPLACED. Use set_subscriber_tags to add tags without replacing the whole set.'];
+                    }
+                }
+            }
+            updates.updated_at = new Date().toISOString();
+            const { data, error } = await db()
+                .from('subscribers')
+                .update(updates)
+                .eq('id', contact_id)
+                .eq('project_id', projectId)
+                .select(embedOk ? UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY : UPDATE_SUBSCRIBER_SELECT_NO_COMPANY)
+                .single();
+            if (error?.code === '23505' && updates.phone_e164 !== undefined) {
+                return contactInputError('conflict', 'Another contact in this project already has this phone number.');
+            }
+            if (error)
+                return dbErrorResult(error);
+            if (customPropertyChanges.length > 0) {
+                logAudit({
+                    action: 'contact.custom_properties_changed',
+                    resourceType: 'contact',
+                    resourceId: contact_id,
+                    details: { changes: customPropertyChanges },
+                });
+            }
+            await writeBackMcpContact(projectId, data, {
+                ...(updates.email !== undefined ? { email: updates.email } : {}),
+                ...(updates.first_name !== undefined ? { first_name: updates.first_name } : {}),
+                ...(updates.last_name !== undefined ? { last_name: updates.last_name } : {}),
+                ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
+                ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
             });
+            const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings];
+            return j({ ...data, ...tagResult, ...(mergedWarnings.length ? { warnings: mergedWarnings } : {}) });
+        }
+        catch (error) {
+            return dbErrorResult(error);
         }
-        await writeBackMcpContact(projectId, data, {
-            ...(updates.email !== undefined ? { email: updates.email } : {}),
-            ...(updates.first_name !== undefined ? { first_name: updates.first_name } : {}),
-            ...(updates.last_name !== undefined ? { last_name: updates.last_name } : {}),
-            ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
-            ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
-        });
-        const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings];
-        return j({ ...data, ...tagResult, ...(mergedWarnings.length ? { warnings: mergedWarnings } : {}) });
     });
     server.registerTool('get_subscriber', {
         title: 'Get Subscriber',
@@ -2045,18 +2144,23 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         },
     }, async ({ contact_ids, add_tags = [], remove_tags = [] }) => {
         if (!add_tags.length && !remove_tags.length)
-            return txt('No tags to add or remove.');
+            return toolError({ error: 'No tags to add or remove.', code: 'validation_failed' });
         const projectId = getProjectId();
         let updated = 0;
+        const missing_contact_ids = [];
         for (const cid of contact_ids) {
-            const { data: contact } = await db()
+            const { data: contact, error: readError } = await db()
                 .from('subscribers')
                 .select('id, email, first_name, last_name, custom_properties, tags')
                 .eq('id', cid)
                 .eq('project_id', projectId)
                 .maybeSingle();
-            if (!contact)
+            if (readError)
+                return toolError({ ...dbToolError(readError), updated });
+            if (!contact) {
+                missing_contact_ids.push(cid);
                 continue;
+            }
             const currentTags = contact.tags ?? [];
             const removeSet = new Set(remove_tags);
             const merged = currentTags.filter((t) => !removeSet.has(t));
@@ -2064,17 +2168,25 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 if (!merged.includes(t))
                     merged.push(t);
             }
-            const { error } = await db()
+            const { data: saved, error } = await db()
                 .from('subscribers')
                 .update({ tags: merged })
                 .eq('id', cid)
-                .eq('project_id', projectId);
-            if (!error) {
-                updated++;
-                await writeBackMcpContact(projectId, contact, { tags: merged });
+                .eq('project_id', projectId)
+                .select('id').maybeSingle();
+            if (error)
+                return toolError({ ...dbToolError(error), updated });
+            if (!saved) {
+                missing_contact_ids.push(cid);
+                continue;
             }
+            updated++;
+            await writeBackMcpContact(projectId, contact, { tags: merged });
+            await logAudit({ action: 'subscriber.tags_updated', resourceType: 'subscriber', resourceId: cid, details: { add_tags, remove_tags } });
         }
-        return j({ updated, total: contact_ids.length, add_tags, remove_tags });
+        if (!updated)
+            return toolError({ error: 'Subscriber not found', code: 'not_found', updated, missing_contact_ids });
+        return j({ missing_contact_ids, updated, total: contact_ids.length, add_tags, remove_tags });
     });
     server.registerTool('bulk_update_subscribers', {
         title: 'Bulk Update Subscribers',