@sendinel/mcp-server 1.0.0

package/build/tools/advisor.js

@@ -0,0 +1,762 @@
+import { z } from 'zod';
+import Anthropic from '@anthropic-ai/sdk';
+import { db } from '../db.js';
+import { getProjectId } from '../project.js';
+import { buildVoicePrompt } from '../lib/voice.js';
+import { getAnthropicModelId } from '../anthropic-model.js';
+const txt = (text) => ({ content: [{ type: 'text', text }] });
+const j = (data) => txt(JSON.stringify(data, null, 2));
+const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+export function computeMetrics(rows) {
+    const sent = rows.length;
+    const delivered = rows.filter((r) => ['delivered', 'opened', 'clicked'].includes(r.status)).length;
+    const opened = rows.filter((r) => ['opened', 'clicked'].includes(r.status)).length;
+    const clicked = rows.filter((r) => r.status === 'clicked').length;
+    const bounced = rows.filter((r) => r.status === 'bounced').length;
+    const complained = rows.filter((r) => r.status === 'complained').length;
+    return {
+        sent,
+        delivered,
+        opened,
+        clicked,
+        bounced,
+        complained,
+        open_rate: sent > 0 ? +(opened / sent * 100).toFixed(2) : 0,
+        click_rate: sent > 0 ? +(clicked / sent * 100).toFixed(2) : 0,
+        bounce_rate: sent > 0 ? +(bounced / sent * 100).toFixed(2) : 0,
+        complaint_rate: sent > 0 ? +(complained / sent * 100).toFixed(2) : 0,
+    };
+}
+export function buildTimeBuckets(rows, groupBy, metric) {
+    const buckets = new Map();
+    for (const row of rows) {
+        const date = new Date(row.created_at);
+        const key = groupBy === 'hour' ? date.getUTCHours() : date.getUTCDay();
+        const entry = buckets.get(key) ?? { sends: 0, engagements: 0 };
+        entry.sends++;
+        const engaged = metric === 'click_rate'
+            ? row.status === 'clicked'
+            : ['opened', 'clicked'].includes(row.status);
+        if (engaged)
+            entry.engagements++;
+        buckets.set(key, entry);
+    }
+    const results = [];
+    for (const [key, val] of buckets.entries()) {
+        if (val.sends < 10)
+            continue;
+        results.push({
+            label: groupBy === 'hour' ? `${key.toString().padStart(2, '0')}:00 UTC` : DAY_NAMES[key],
+            sends: val.sends,
+            engagements: val.engagements,
+            rate: +(val.engagements / val.sends * 100).toFixed(2),
+        });
+    }
+    results.sort((a, b) => b.rate - a.rate);
+    return results;
+}
+// ── Registration ──────────────────────────────────────────────────────
+export function registerAdvisorTools(server) {
+    server.registerTool('run_portfolio_analysis', {
+        description: 'Run a grounded portfolio health analysis across active campaigns.',
+        inputSchema: { force_run: z.boolean().optional().default(false) },
+    }, async ({ force_run = false }) => {
+        const projectId = getProjectId();
+        const since = new Date(Date.now() - 30 * 86400000).toISOString();
+        const { data: campaigns, error } = await db().from('campaigns').select('id, name, type').eq('project_id', projectId).eq('status', 'active').limit(200);
+        if (error)
+            return j({ error: error.message });
+        const recommendations = [];
+        let skipped = 0;
+        for (const campaign of campaigns ?? []) {
+            const { data: logs } = await db().from('email_log').select('status').eq('project_id', projectId).eq('campaign_id', campaign.id).gte('created_at', since).limit(10000);
+            const rows = logs ?? [];
+            const sends = rows.filter((row) => ['sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained'].includes(row.status)).length;
+            if (sends < 100) {
+                skipped++;
+                continue;
+            }
+            const bounces = rows.filter((row) => row.status === 'bounced').length;
+            const bounceRate = sends ? Number(((bounces / sends) * 100).toFixed(1)) : 0;
+            recommendations.push({
+                campaign_id: campaign.id,
+                campaign_name: campaign.name,
+                metric_name: 'bounce_rate',
+                metric_value: bounceRate,
+                sample_size: sends,
+                confidence: sends >= 500 ? 'HIGH' : 'MEDIUM',
+                data_citation: `${bounceRate}% bounce rate from ${sends} sends over 30 days`,
+                recommendation_text: bounceRate >= 5
+                    ? `Review list quality before sending more from ${campaign.name}. Bounce rate is ${bounceRate}% from ${sends} sends.`
+                    : `${campaign.name} has acceptable bounce pressure at ${bounceRate}% from ${sends} sends.`,
+            });
+        }
+        const next = new Date();
+        next.setUTCDate(next.getUTCDate() + ((8 - next.getUTCDay()) % 7 || 7));
+        next.setUTCHours(6, 0, 0, 0);
+        return j({ campaigns_analyzed: campaigns?.length ?? 0, recommendations, skipped_insufficient_data: skipped, next_scheduled: next.toISOString(), force_run });
+    });
+    // ── 1. campaign_advisor ────────────────────────────────────────────
+    server.registerTool('campaign_advisor', {
+        description: 'Analyze campaign performance and get actionable recommendations. Returns period-over-period metrics, domain health issues, engagement distribution, and prioritized recommendations with severity levels.',
+        inputSchema: {
+            site_id: z.string().uuid().optional().describe('Filter to a specific site'),
+            days: z.number().int().min(1).max(365).optional().default(30).describe('Analysis period in days (default: 30)'),
+        },
+    }, async ({ site_id, days: daysParam }) => {
+        const projectId = getProjectId();
+        const days = daysParam ?? 30;
+        const now = new Date();
+        const periodStart = new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
+        const priorStart = new Date(periodStart.getTime() - days * 24 * 60 * 60 * 1000);
+        // 1. Current period email_log
+        let currentQuery = db()
+            .from('email_log')
+            .select('status, created_at')
+            .eq('project_id', projectId)
+            .gte('created_at', periodStart.toISOString())
+            .limit(10000);
+        if (site_id)
+            currentQuery = currentQuery.eq('site_id', site_id);
+        const { data: currentRows } = await currentQuery;
+        // 2. Prior period
+        let priorQuery = db()
+            .from('email_log')
+            .select('status, created_at')
+            .eq('project_id', projectId)
+            .gte('created_at', priorStart.toISOString())
+            .lt('created_at', periodStart.toISOString())
+            .limit(10000);
+        if (site_id)
+            priorQuery = priorQuery.eq('site_id', site_id);
+        const { data: priorRows } = await priorQuery;
+        const current = computeMetrics(currentRows ?? []);
+        const prior = computeMetrics(priorRows ?? []);
+        // 3. Domain health (latest per site)
+        let healthQuery = db()
+            .from('domain_health')
+            .select('site_id, bounce_rate, complaint_rate, spf_valid, dkim_valid, dmarc_valid, warmup_day')
+            .eq('project_id', projectId)
+            .order('check_date', { ascending: false })
+            .limit(20);
+        if (site_id)
+            healthQuery = healthQuery.eq('site_id', site_id);
+        const { data: healthRows } = await healthQuery;
+        // Deduplicate: keep only latest per site_id
+        const healthBySite = new Map();
+        for (const row of healthRows ?? []) {
+            if (!healthBySite.has(row.site_id))
+                healthBySite.set(row.site_id, row);
+        }
+        // 4. Engagement summary
+        const { data: engagementSummary } = await db()
+            .rpc('get_engagement_summary', { p_project_id: projectId });
+        // 5. Unpromoted A/B test winners
+        const { data: unpromoted } = await db()
+            .from('ab_tests')
+            .select('id, name, winner, campaign_id')
+            .eq('project_id', projectId)
+            .eq('status', 'significant');
+        // 6. Build recommendations
+        const recommendations = [];
+        // No recent sends
+        if (current.sent === 0) {
+            recommendations.push({
+                type: 'no_recent_sends',
+                severity: 'info',
+                message: `No emails sent in the last ${days} days.`,
+            });
+        }
+        // High bounce rate
+        if (current.sent > 0 && current.bounce_rate > 5) {
+            recommendations.push({
+                type: 'high_bounce_rate',
+                severity: 'critical',
+                message: `Bounce rate is ${current.bounce_rate}% (threshold: 5%).`,
+                detail: 'Clean your list: remove hard bounces, verify email addresses, check for typos in imported data.',
+            });
+        }
+        // High complaint rate
+        if (current.sent > 0 && current.complaint_rate > 0.3) {
+            recommendations.push({
+                type: 'high_complaint_rate',
+                severity: 'critical',
+                message: `Complaint rate is ${current.complaint_rate}% (threshold: 0.3%).`,
+                detail: 'Review email content and frequency. Ensure clear unsubscribe links. Consider re-permission campaign.',
+            });
+        }
+        // Open rate declining
+        if (prior.sent >= 50 && current.sent >= 50) {
+            const delta = current.open_rate - prior.open_rate;
+            if (delta < -10) {
+                recommendations.push({
+                    type: 'open_rate_declining',
+                    severity: 'warning',
+                    message: `Open rate dropped ${Math.abs(delta).toFixed(1)}pp (${prior.open_rate}% → ${current.open_rate}%).`,
+                    detail: 'Test different subject lines with optimize_subject_lines. Check if you are hitting spam filters.',
+                });
+            }
+        }
+        // Low click-to-open
+        if (current.opened >= 50) {
+            const cto = +(current.clicked / current.opened * 100).toFixed(2);
+            if (cto < 5) {
+                recommendations.push({
+                    type: 'low_click_to_open',
+                    severity: 'warning',
+                    message: `Click-to-open rate is ${cto}% (threshold: 5%).`,
+                    detail: 'Improve CTA clarity and placement. Ensure one clear call-to-action per email.',
+                });
+            }
+        }
+        // Volume spike
+        if (prior.sent > 0 && current.sent > prior.sent * 3) {
+            recommendations.push({
+                type: 'volume_spike',
+                severity: 'warning',
+                message: `Send volume jumped ${(current.sent / prior.sent).toFixed(1)}x vs prior period (${prior.sent} → ${current.sent}).`,
+                detail: 'Sudden volume increases can trigger spam filters. Consider ramping up gradually.',
+            });
+        }
+        // Cold contacts growing
+        if (engagementSummary) {
+            const summary = typeof engagementSummary === 'string' ? JSON.parse(engagementSummary) : engagementSummary;
+            const lifecycle = summary?.lifecycle_distribution;
+            if (lifecycle) {
+                const total = Object.values(lifecycle).reduce((a, b) => a + Number(b), 0);
+                const coldChurned = (Number(lifecycle.cold ?? 0) + Number(lifecycle.churned ?? 0));
+                if (total > 0 && (coldChurned / total) > 0.3) {
+                    recommendations.push({
+                        type: 'cold_contacts_growing',
+                        severity: 'warning',
+                        message: `${((coldChurned / total) * 100).toFixed(0)}% of contacts are cold or churned.`,
+                        detail: 'Run a re-engagement campaign or remove inactive contacts to improve deliverability.',
+                    });
+                }
+            }
+        }
+        // Warmup stalled
+        for (const health of healthBySite.values()) {
+            if (health.warmup_day > 7 && (health.bounce_rate ?? 0) > 3) {
+                recommendations.push({
+                    type: 'warmup_stalled',
+                    severity: 'warning',
+                    message: `Domain warmup day ${health.warmup_day} but bounce rate is ${health.bounce_rate}%.`,
+                    detail: 'Warmup is at risk. Reduce volume or pause sending for 48 hours to recover.',
+                });
+            }
+        }
+        // Unpromoted A/B winners
+        for (const test of unpromoted ?? []) {
+            recommendations.push({
+                type: 'unpromoted_ab_winner',
+                severity: 'info',
+                message: `A/B test "${test.name}" has a significant winner (${test.winner}) but hasn't been promoted.`,
+                detail: `Use promote_ab_winner with test_id ${test.id} to keep the winning variant.`,
+            });
+        }
+        // Sort: critical > warning > info
+        const severityOrder = { critical: 0, warning: 1, info: 2 };
+        recommendations.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+        const hasCritical = recommendations.some(r => r.severity === 'critical');
+        const hasWarning = recommendations.some(r => r.severity === 'warning');
+        const overall = hasCritical ? 'CRITICAL' : hasWarning ? 'NEEDS_ATTENTION' : 'HEALTHY';
+        const trends = prior.sent > 0 ? {
+            open_rate_delta: +(current.open_rate - prior.open_rate).toFixed(2),
+            click_rate_delta: +(current.click_rate - prior.click_rate).toFixed(2),
+            bounce_rate_delta: +(current.bounce_rate - prior.bounce_rate).toFixed(2),
+            volume_change: +((current.sent - prior.sent) / prior.sent * 100).toFixed(1),
+        } : null;
+        return j({
+            period: { days, from: periodStart.toISOString().split('T')[0], to: now.toISOString().split('T')[0] },
+            current_metrics: current,
+            prior_metrics: prior.sent > 0 ? prior : null,
+            trends,
+            recommendations,
+            overall,
+        });
+    });
+    // ── 2. optimize_subject_lines ──────────────────────────────────────
+    server.registerTool('optimize_subject_lines', {
+        description: 'Generate optimized subject line variants using AI, informed by historical top performers and brand voice. Optionally creates campaign step variants for A/B testing.',
+        inputSchema: {
+            campaign_id: z.string().uuid(),
+            step_order: z.number().int().min(0).optional().default(0),
+            count: z.number().int().min(1).max(10).optional().default(5).describe('Number of suggestions'),
+            site_id: z.string().uuid().describe('Site for brand voice context'),
+            create_variants: z.boolean().optional().default(false).describe('If true, insert top 2 as campaign step variants B and C'),
+        },
+    }, async ({ campaign_id, step_order, count, site_id, create_variants }) => {
+        const projectId = getProjectId();
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey)
+            return txt('Error: ANTHROPIC_API_KEY not configured.');
+        // 1. Get current subject (variant A)
+        const { data: currentStep } = await db()
+            .from('campaign_steps')
+            .select('id, subject, html_body, text_body, delay_days, delay_hours')
+            .eq('campaign_id', campaign_id)
+            .eq('step_order', step_order ?? 0)
+            .eq('variant_label', 'A')
+            .maybeSingle();
+        if (!currentStep)
+            return txt(`Error: No campaign step found for step_order ${step_order ?? 0}, variant A.`);
+        // 2. Top-performing historical subjects
+        let logQuery = db()
+            .from('email_log')
+            .select('subject, status')
+            .eq('project_id', projectId)
+            .in('status', ['delivered', 'opened', 'clicked'])
+            .limit(5000);
+        if (site_id)
+            logQuery = logQuery.eq('site_id', site_id);
+        const { data: logRows } = await logQuery;
+        // Aggregate by subject
+        const subjectStats = new Map();
+        for (const row of logRows ?? []) {
+            if (!row.subject)
+                continue;
+            const entry = subjectStats.get(row.subject) ?? { sent: 0, opened: 0 };
+            entry.sent++;
+            if (['opened', 'clicked'].includes(row.status))
+                entry.opened++;
+            subjectStats.set(row.subject, entry);
+        }
+        const topPerformers = Array.from(subjectStats.entries())
+            .filter(([, stats]) => stats.sent >= 50)
+            .map(([subject, stats]) => ({
+            subject,
+            open_rate: +(stats.opened / stats.sent * 100).toFixed(1),
+            sample_size: stats.sent,
+        }))
+            .sort((a, b) => b.open_rate - a.open_rate)
+            .slice(0, 5);
+        // 3. Brand voice
+        const { data: site } = await db()
+            .from('sites')
+            .select('name, brand_voice')
+            .eq('id', site_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        const voicePrompt = buildVoicePrompt(site?.brand_voice);
+        // 4. Call Claude
+        const anthropic = new Anthropic({ apiKey });
+        const topPerformerContext = topPerformers.length > 0
+            ? `\n\nTop-performing historical subjects for reference:\n${topPerformers.map(tp => `- "${tp.subject}" (${tp.open_rate}% open rate, ${tp.sample_size} sends)`).join('\n')}`
+            : '';
+        const response = await anthropic.messages.create({
+            model: getAnthropicModelId(),
+            max_tokens: 1024,
+            system: `You are an email subject line optimization expert. Follow the brand voice rules strictly.\n\n${voicePrompt}`,
+            messages: [{
+                    role: 'user',
+                    content: `Generate ${count ?? 5} subject line alternatives for this email.
+
+Current subject: "${currentStep.subject}"
+${topPerformerContext}
+
+Return ONLY a JSON array: [{"subject": "...", "rationale": "..."}]
+Each subject should be distinct in approach (urgency, curiosity, benefit, social proof, etc). Keep them under 60 characters. No emojis. No clickbait. No em dashes.`,
+                }],
+        });
+        const textBlock = response.content.find((b) => b.type === 'text');
+        const raw = textBlock && 'text' in textBlock ? textBlock.text : '[]';
+        let suggestions;
+        try {
+            suggestions = JSON.parse(raw.replace(/```json?\n?|```/g, '').trim());
+        }
+        catch {
+            return txt(`Error: Failed to parse AI response. Raw: ${raw.slice(0, 200)}`);
+        }
+        // 5. Optionally create variants
+        let variantsCreated;
+        if (create_variants && suggestions.length >= 2) {
+            const labels = ['B', 'C'];
+            variantsCreated = [];
+            for (let i = 0; i < 2; i++) {
+                const { error: insertErr } = await db()
+                    .from('campaign_steps')
+                    .insert({
+                    campaign_id,
+                    step_order: step_order ?? 0,
+                    variant_label: labels[i],
+                    subject: suggestions[i].subject,
+                    html_body: currentStep.html_body,
+                    text_body: currentStep.text_body,
+                    delay_days: currentStep.delay_days,
+                    delay_hours: currentStep.delay_hours,
+                });
+                if (!insertErr)
+                    variantsCreated.push(labels[i]);
+            }
+        }
+        return j({
+            current_subject: currentStep.subject,
+            suggestions,
+            top_performers_used: topPerformers,
+            variants_created: variantsCreated,
+            next_step: create_variants && variantsCreated?.length
+                ? 'Variants created. Use create_ab_test to set up an A/B test for this step.'
+                : 'Review suggestions and use add_campaign_step with variant_label to create variants manually.',
+        });
+    });
+    // ── 3. suggest_content_topics ────────────────────────────────────
+    server.registerTool('suggest_content_topics', {
+        description: 'Analyze past email performance and recommend content topics for future emails. Uses AI to identify patterns in high- and low-performing content, then suggests specific topics with expected engagement levels.',
+        inputSchema: {
+            site_id: z.string().uuid().describe('Site UUID to analyze'),
+            days: z.number().int().min(7).max(365).optional().default(90).describe('Days of history to analyze (default: 90)'),
+        },
+    }, async ({ site_id, days: daysParam }) => {
+        const projectId = getProjectId();
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey)
+            return txt('Error: ANTHROPIC_API_KEY not configured.');
+        const days = daysParam ?? 90;
+        const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        // 1. Query email_log with campaign step subjects
+        const { data: logRows } = await db()
+            .from('email_log')
+            .select('campaign_id, subject, status')
+            .eq('project_id', projectId)
+            .eq('site_id', site_id)
+            .gte('created_at', since)
+            .not('campaign_id', 'is', null)
+            .limit(10000);
+        if (!logRows || logRows.length < 20) {
+            return j({
+                error: 'insufficient_data',
+                message: `Only ${logRows?.length ?? 0} campaign emails found in the last ${days} days. Need at least 20 for meaningful analysis.`,
+            });
+        }
+        // 2. Group by campaign + subject, compute engagement
+        const campaignStats = new Map();
+        for (const row of logRows) {
+            const key = `${row.campaign_id}::${row.subject ?? '(no subject)'}`;
+            const entry = campaignStats.get(key) ?? { subject: row.subject ?? '(no subject)', sent: 0, opened: 0, clicked: 0 };
+            entry.sent++;
+            if (['opened', 'clicked'].includes(row.status))
+                entry.opened++;
+            if (row.status === 'clicked')
+                entry.clicked++;
+            campaignStats.set(key, entry);
+        }
+        // 3. Compute rates and sort by composite score
+        const ranked = Array.from(campaignStats.values())
+            .filter(s => s.sent >= 5)
+            .map(s => ({
+            subject: s.subject,
+            sent: s.sent,
+            open_rate: +(s.opened / s.sent * 100).toFixed(1),
+            click_rate: +(s.clicked / s.sent * 100).toFixed(1),
+            score: +(s.opened / s.sent * 0.6 + s.clicked / s.sent * 0.4).toFixed(4),
+        }))
+            .sort((a, b) => b.score - a.score);
+        const topPerformers = ranked.slice(0, 10);
+        const bottomPerformers = ranked.slice(-5);
+        if (topPerformers.length < 3) {
+            return j({
+                error: 'insufficient_data',
+                message: `Only ${topPerformers.length} campaigns with enough sends to analyze. Need at least 3 for meaningful suggestions.`,
+            });
+        }
+        // 4. Brand voice context
+        const { data: site } = await db()
+            .from('sites')
+            .select('name, brand_voice')
+            .eq('id', site_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        const voicePrompt = buildVoicePrompt(site?.brand_voice);
+        // 5. Call Claude
+        const anthropic = new Anthropic({ apiKey });
+        const topContext = topPerformers.map(t => `- "${t.subject}" (open: ${t.open_rate}%, click: ${t.click_rate}%)`).join('\n');
+        const bottomContext = bottomPerformers.map(t => `- "${t.subject}" (open: ${t.open_rate}%, click: ${t.click_rate}%)`).join('\n');
+        const response = await anthropic.messages.create({
+            model: getAnthropicModelId(),
+            max_tokens: 1500,
+            system: `You are an email content strategist. Analyze email performance data and suggest future content topics.\n\n${voicePrompt}`,
+            messages: [{
+                    role: 'user',
+                    content: `Analyze these email performance results and suggest 5 content topics for future emails.
+
+Top performing emails (high engagement):
+${topContext}
+
+Low performing emails:
+${bottomContext}
+
+Based on what resonated vs what didn't, suggest:
+1. 5 specific topic ideas with expected engagement level
+2. Content patterns that work (length, tone, CTA style)
+3. Topics to avoid based on poor performance
+
+Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rationale": "...", "confidence": "high|medium|low" }], "patterns": { "works": ["..."], "avoid": ["..."] } }`,
+                }],
+        });
+        const textBlock = response.content.find((b) => b.type === 'text');
+        const raw = textBlock && 'text' in textBlock ? textBlock.text : '{}';
+        let suggestions;
+        try {
+            suggestions = JSON.parse(raw.replace(/```json?\n?|```/g, '').trim());
+        }
+        catch {
+            return txt(`Error: Failed to parse AI response. Raw: ${raw.slice(0, 300)}`);
+        }
+        return j({
+            site: site?.name ?? site_id,
+            period_days: days,
+            emails_analyzed: logRows.length,
+            campaigns_analyzed: ranked.length,
+            top_performers: topPerformers,
+            bottom_performers: bottomPerformers,
+            suggestions,
+        });
+    });
+    // ── 4. suggest_send_time ───────────────────────────────────────────
+    server.registerTool('suggest_send_time', {
+        description: 'Analyze historical engagement patterns to recommend optimal send times. Groups by hour-of-day and day-of-week to identify when your audience is most responsive.',
+        inputSchema: {
+            site_id: z.string().uuid(),
+            segment_id: z.string().uuid().optional().describe('Narrow analysis to a specific segment'),
+            days: z.number().int().min(7).max(365).optional().default(90).describe('Lookback period in days'),
+            metric: z.enum(['open_rate', 'click_rate']).optional().default('open_rate'),
+        },
+    }, async ({ site_id, segment_id, days: daysParam, metric }) => {
+        const projectId = getProjectId();
+        const days = daysParam ?? 90;
+        const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        // 1. Get contact IDs for segment filter
+        let contactFilter = null;
+        if (segment_id) {
+            const { data: segContacts } = await db()
+                .from('subscribers')
+                .select('id')
+                .eq('project_id', projectId)
+                .limit(5000);
+            // For now, we pass all contacts and filter at query time
+            // A proper segment query would use segment-query.ts, but MCP server
+            // doesn't have that module. We filter by site instead.
+            contactFilter = (segContacts ?? []).map((c) => c.id);
+        }
+        // 2. Query email_log
+        let query = db()
+            .from('email_log')
+            .select('status, created_at')
+            .eq('project_id', projectId)
+            .eq('site_id', site_id)
+            .gte('created_at', since)
+            .in('status', ['delivered', 'opened', 'clicked'])
+            .limit(10000);
+        if (contactFilter) {
+            query = query.in('contact_id', contactFilter.slice(0, 500));
+        }
+        const { data: rows } = await query;
+        if (!rows || rows.length < 30) {
+            return j({
+                error: 'insufficient_data',
+                message: `Only ${rows?.length ?? 0} qualifying emails found in the last ${days} days. Need at least 30 for meaningful analysis.`,
+            });
+        }
+        // 3. Build buckets
+        const hourBuckets = buildTimeBuckets(rows, 'hour', metric ?? 'open_rate');
+        const dayBuckets = buildTimeBuckets(rows, 'day', metric ?? 'open_rate');
+        const best3Hours = hourBuckets.slice(0, 3);
+        const worst3Hours = hourBuckets.slice(-3).reverse();
+        const best3Days = dayBuckets.slice(0, 3);
+        const worst3Days = dayBuckets.slice(-3).reverse();
+        const topHour = best3Hours[0];
+        const topDay = best3Days[0];
+        const recommendation = topHour && topDay
+            ? `Best performance: ${topDay.label}s at ${topHour.label} (${topHour.rate}% ${metric ?? 'open_rate'}).`
+            : 'Not enough data across time slots to make a recommendation.';
+        return j({
+            metric: metric ?? 'open_rate',
+            period_days: days,
+            total_emails_analyzed: rows.length,
+            best_hours: best3Hours,
+            worst_hours: worst3Hours,
+            best_days: best3Days,
+            worst_days: worst3Days,
+            recommendation,
+        });
+    });
+    // ── 5. recovery_plan ───────────────────────────────────────────────
+    server.registerTool('recovery_plan', {
+        description: 'Analyze deliverability issues for a site and generate a structured recovery plan. Examines domain health (SPF/DKIM/DMARC), bounce/complaint rates, recent send stats, and new suppressions to produce prioritized immediate, short-term, and monitoring steps. Deterministic — no AI call, pure rule-based analysis.',
+        inputSchema: {
+            site_id: z.string().uuid().describe('Site UUID with deliverability issues'),
+        },
+    }, async ({ site_id }) => {
+        const projectId = getProjectId();
+        // 1. Verify site ownership
+        const { data: site, error: siteErr } = await db()
+            .from('sites')
+            .select('id, slug, name, sending_domain, from_email')
+            .eq('id', site_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (siteErr || !site)
+            return txt(`Error: Site not found — ${siteErr?.message ?? 'not found'}`);
+        // 2. Fetch latest domain_health
+        const { data: healthRows } = await db()
+            .from('domain_health')
+            .select('spf_valid, dkim_valid, dmarc_valid, bounce_rate, complaint_rate, warmup_day, warmup_daily_limit, delivery_rate, total_sent')
+            .eq('site_id', site_id)
+            .order('check_date', { ascending: false })
+            .limit(1);
+        const health = (healthRows ?? [])[0];
+        const spfValid = health?.spf_valid ?? false;
+        const dkimValid = health?.dkim_valid ?? false;
+        const dmarcValid = health?.dmarc_valid ?? false;
+        const warmupDay = health?.warmup_day ?? null;
+        const warmupDailyLimit = health?.warmup_daily_limit ?? null;
+        // 3. Fetch recent 7-day email_log stats
+        const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+        const { data: recentLogs } = await db()
+            .from('email_log')
+            .select('status, opened_at, clicked_at')
+            .eq('project_id', projectId)
+            .eq('site_id', site_id)
+            .gte('sent_at', sevenDaysAgo);
+        const logs = recentLogs ?? [];
+        const totalSent = logs.length;
+        const bounced = logs.filter((l) => l.status === 'bounced').length;
+        const complained = logs.filter((l) => l.status === 'complained').length;
+        const delivered = logs.filter((l) => ['delivered', 'opened', 'clicked'].includes(l.status)).length;
+        const opened = logs.filter((l) => l.opened_at).length;
+        const bounceRate = totalSent > 0 ? +(bounced / totalSent * 100).toFixed(2) : 0;
+        const complaintRate = totalSent > 0 ? +(complained / totalSent * 100).toFixed(2) : 0;
+        const openRate = totalSent > 0 ? +(opened / totalSent * 100).toFixed(2) : 0;
+        // 4. Fetch new suppressions this week
+        const { count: newSuppressions } = await db()
+            .from('suppressions')
+            .select('id', { count: 'exact', head: true })
+            .eq('project_id', projectId)
+            .gte('created_at', sevenDaysAgo);
+        const issues = [];
+        if (bounceRate > 5)
+            issues.push({ type: 'high_bounce', severity: 'critical', detail: `Bounce rate ${bounceRate}% exceeds 5% threshold` });
+        else if (bounceRate > 2)
+            issues.push({ type: 'elevated_bounce', severity: 'high', detail: `Bounce rate ${bounceRate}% approaching danger zone` });
+        if (complaintRate > 0.3)
+            issues.push({ type: 'high_complaint', severity: 'critical', detail: `Complaint rate ${complaintRate}% exceeds 0.3% threshold` });
+        else if (complaintRate > 0.1)
+            issues.push({ type: 'elevated_complaint', severity: 'high', detail: `Complaint rate ${complaintRate}% approaching danger zone` });
+        if (!spfValid || !dkimValid)
+            issues.push({ type: 'dns_invalid', severity: 'high', detail: `Missing DNS: ${!spfValid ? 'SPF' : ''}${!spfValid && !dkimValid ? ' + ' : ''}${!dkimValid ? 'DKIM' : ''}` });
+        if (!dmarcValid)
+            issues.push({ type: 'no_dmarc', severity: 'medium', detail: 'DMARC record missing or invalid' });
+        if (warmupDay != null && warmupDay < 42 && bounceRate > 3) {
+            issues.push({ type: 'warmup_risk', severity: 'high', detail: `Domain on warmup day ${warmupDay} with ${bounceRate}% bounce rate — warmup at risk` });
+        }
+        if (totalSent === 0) {
+            issues.push({ type: 'no_recent_sends', severity: 'low', detail: 'No sends in the last 7 days — no active data to assess' });
+        }
+        // 6. Build recovery plan steps
+        const immediate = [];
+        const shortTerm = [];
+        const monitoring = [];
+        // Critical: pause sending
+        if (bounceRate > 8 || complaintRate > 0.5) {
+            immediate.push('Pause all active campaigns immediately');
+            immediate.push('Review and suppress all hard-bounced contacts');
+            monitoring.push('Wait 48 hours before resuming any sends');
+        }
+        else if (bounceRate > 5 || complaintRate > 0.3) {
+            immediate.push('Pause marketing campaigns (transactional OK)');
+            immediate.push('Review recent bounce reasons in suppression log');
+        }
+        // DNS fixes
+        if (!spfValid)
+            immediate.push('Add SPF record for sending domain');
+        if (!dkimValid)
+            immediate.push('Configure DKIM record (CNAME for resend._domainkey)');
+        if (!dmarcValid)
+            shortTerm.push('Add DMARC record (start with p=none for monitoring)');
+        // List hygiene
+        if (bounceRate > 2 || complained > 0) {
+            shortTerm.push('Run identify_inactive to find cold contacts and suppress them');
+            shortTerm.push(`Suppress ${newSuppressions ?? 0} newly identified problem addresses`);
+        }
+        // Volume reduction
+        if (bounceRate > 3 && warmupDailyLimit) {
+            const reducedLimit = Math.max(10, Math.floor(warmupDailyLimit * 0.5));
+            shortTerm.push(`Reduce daily volume to ${reducedLimit}/day (50% of current limit) for 48 hours`);
+        }
+        else if (bounceRate > 3) {
+            shortTerm.push('Reduce daily send volume by 50% for at least 48 hours');
+        }
+        // Re-verification
+        if (!spfValid || !dkimValid) {
+            shortTerm.push('Re-verify domain after DNS changes (use dns-verify API)');
+        }
+        // Monitoring steps
+        monitoring.push('Check bounce rate daily for 7 days');
+        monitoring.push('Monitor complaint rate — must stay below 0.3%');
+        if (bounceRate > 5 || complaintRate > 0.3) {
+            monitoring.push('Re-assess after 48h pause before resuming');
+            monitoring.push('Resume at 25% of normal volume, ramp over 5 days');
+        }
+        if (warmupDay != null && warmupDay < 42) {
+            monitoring.push(`Continue warmup protocol — currently day ${warmupDay} of 42`);
+        }
+        // 7. Compute health score (0-100)
+        let healthScore = 100;
+        if (!spfValid)
+            healthScore -= 15;
+        if (!dkimValid)
+            healthScore -= 15;
+        if (!dmarcValid)
+            healthScore -= 5;
+        if (bounceRate > 8)
+            healthScore -= 30;
+        else if (bounceRate > 5)
+            healthScore -= 20;
+        else if (bounceRate > 2)
+            healthScore -= 10;
+        if (complaintRate > 0.5)
+            healthScore -= 25;
+        else if (complaintRate > 0.3)
+            healthScore -= 15;
+        else if (complaintRate > 0.1)
+            healthScore -= 5;
+        if (warmupDay != null && warmupDay < 42 && bounceRate > 3)
+            healthScore -= 10;
+        healthScore = Math.max(0, healthScore);
+        // 8. Estimate recovery time
+        let estimatedRecovery = '1-2 days';
+        if (bounceRate > 8 || complaintRate > 0.5)
+            estimatedRecovery = '7-14 days';
+        else if (bounceRate > 5 || complaintRate > 0.3)
+            estimatedRecovery = '5-7 days';
+        else if (!spfValid || !dkimValid)
+            estimatedRecovery = '2-3 days';
+        else if (bounceRate > 2)
+            estimatedRecovery = '3-5 days';
+        return j({
+            site: { id: site.id, slug: site.slug, domain: site.sending_domain },
+            health_score: healthScore,
+            recent_7d: {
+                total_sent: totalSent,
+                delivered,
+                bounced,
+                complained,
+                opened,
+                bounce_rate: `${bounceRate}%`,
+                complaint_rate: `${complaintRate}%`,
+                open_rate: `${openRate}%`,
+            },
+            dns: { spf_valid: spfValid, dkim_valid: dkimValid, dmarc_valid: dmarcValid },
+            warmup: warmupDay != null ? { day: warmupDay, daily_limit: warmupDailyLimit } : null,
+            new_suppressions_7d: newSuppressions ?? 0,
+            issues,
+            plan: {
+                immediate: immediate.length > 0 ? immediate : ['No immediate action required'],
+                short_term: shortTerm.length > 0 ? shortTerm : ['Continue current sending practices'],
+                monitoring,
+            },
+            estimated_recovery: issues.length === 0 ? 'No recovery needed — site is healthy' : estimatedRecovery,
+        });
+    });
+}