@sendinel/mcp-server 1.0.181 → 1.0.182

package/build/tools/advisor.d.ts

@@ -6,10 +6,10 @@ interface PeriodMetrics {
     clicked: number;
     bounced: number;
     complained: number;
-    open_rate: number;
-    click_rate: number;
-    bounce_rate: number;
-    complaint_rate: number;
+    open_rate: number | null;
+    click_rate: number | null;
+    bounce_rate: number | null;
+    complaint_rate: number | null;
 }
 export declare function computeMetrics(rows: any[]): PeriodMetrics;
 interface TimeBucket {

package/build/tools/advisor.js

@@ -14,12 +14,20 @@ const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Frid
 export function computeMetrics(rows) {
     const counts = countEmailRows(rows);
     return { ...counts,
-        open_rate: percentRate(counts.opened, counts.delivered, 2) ?? 0,
-        click_rate: percentRate(counts.clicked, counts.delivered, 2) ?? 0,
-        bounce_rate: percentRate(counts.bounced, counts.sent, 2) ?? 0,
-        complaint_rate: percentRate(counts.complained, counts.sent, 2) ?? 0,
+        open_rate: percentRate(counts.opened, counts.delivered, 2),
+        click_rate: percentRate(counts.clicked, counts.delivered, 2),
+        bounce_rate: percentRate(counts.bounced, counts.sent, 2),
+        complaint_rate: percentRate(counts.complained, counts.sent, 2),
     };
 }
+// Look up sites in the active project before reading analytics or calling AI.
+function advisorSite(siteId, projectId) {
+    return db().from('sites').select('id, name, brand_voice')
+        .eq('id', siteId).eq('project_id', projectId).maybeSingle();
+}
+function rateDelta(current, prior) {
+    return current === null || prior === null ? null : +(current - prior).toFixed(2);
+}
 export function buildTimeBuckets(rows, groupBy, metric) {
     const buckets = groupMetricRows(rows, row => String(groupBy === "hour" ? new Date(row.created_at).getUTCHours() : new Date(row.created_at).getUTCDay()));
     const results = [];
@@ -91,13 +99,20 @@ export function registerAdvisorTools(server) {
             idempotentHint: true,
             openWorldHint: true,
         },
-        description: 'Analyze campaign performance and get actionable recommendations. Returns period-over-period metrics, domain health issues, engagement distribution, and prioritized recommendations with severity levels.',
+        description: 'Analyze campaign performance and get actionable recommendations. Returns period-over-period metrics, domain health issues, engagement distribution, and prioritized recommendations with severity levels. The overall verdict is an engagement/campaign verdict, not a deliverability verdict.',
         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();
+        if (site_id) {
+            const { data: site, error } = await advisorSite(site_id, projectId);
+            if (error)
+                return toolError(dbToolError(error));
+            if (!site)
+                return toolError({ code: 'not_found', error: 'Site not found' });
+        }
         const days = daysParam ?? 30;
         const now = new Date();
         const periodStart = new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
@@ -159,7 +174,7 @@ export function registerAdvisorTools(server) {
             });
         }
         // High bounce rate
-        if (current.sent > 0 && current.bounce_rate > 5) {
+        if (current.bounce_rate !== null && current.bounce_rate > 5) {
             recommendations.push({
                 type: 'high_bounce_rate',
                 severity: 'critical',
@@ -168,7 +183,7 @@ export function registerAdvisorTools(server) {
             });
         }
         // High complaint rate
-        if (current.sent > 0 && current.complaint_rate > 0.3) {
+        if (current.complaint_rate !== null && current.complaint_rate > 0.3) {
             recommendations.push({
                 type: 'high_complaint_rate',
                 severity: 'critical',
@@ -177,7 +192,7 @@ export function registerAdvisorTools(server) {
             });
         }
         // Open rate declining
-        if (prior.sent >= 50 && current.sent >= 50) {
+        if (prior.sent >= 50 && current.sent >= 50 && prior.open_rate !== null && current.open_rate !== null) {
             const delta = current.open_rate - prior.open_rate;
             if (delta < -10) {
                 recommendations.push({
@@ -253,9 +268,9 @@ export function registerAdvisorTools(server) {
         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),
+            open_rate_delta: rateDelta(current.open_rate, prior.open_rate),
+            click_rate_delta: rateDelta(current.click_rate, prior.click_rate),
+            bounce_rate_delta: rateDelta(current.bounce_rate, prior.bounce_rate),
             volume_change: +((current.sent - prior.sent) / prior.sent * 100).toFixed(1),
         } : null;
         return j({
@@ -286,19 +301,32 @@ export function registerAdvisorTools(server) {
         },
     }, async ({ campaign_id, step_order, count, site_id, create_variants }) => {
         const projectId = getProjectId();
+        const { data: campaign, error: campaignError } = await db()
+            .from('campaigns').select('id').eq('id', campaign_id).eq('project_id', projectId).maybeSingle();
+        if (campaignError)
+            return toolError(dbToolError(campaignError));
+        if (!campaign)
+            return toolError({ code: 'not_found', error: 'Campaign not found' });
+        const { data: site, error: siteError } = await advisorSite(site_id, projectId);
+        if (siteError)
+            return toolError(dbToolError(siteError));
+        if (!site)
+            return toolError({ code: 'not_found', error: 'Site not found' });
         const apiKey = process.env.ANTHROPIC_API_KEY;
         if (!apiKey)
-            return txt('Error: ANTHROPIC_API_KEY not configured.');
+            return toolError({ code: 'internal_error', error: 'ANTHROPIC_API_KEY not configured.' });
         // 1. Get current subject (variant A)
-        const { data: currentStep } = await db()
+        const { data: currentStep, error: stepError } = await db()
             .from('campaign_steps')
             .select('id, subject, html_body:body_html, text_body:body_text, delay_days, delay_hours')
             .eq('campaign_id', campaign_id)
             .eq('step_order', step_order ?? 0)
             .eq('variant_label', 'A')
             .maybeSingle();
+        if (stepError)
+            return toolError(dbToolError(stepError));
         if (!currentStep)
-            return txt(`Error: No campaign step found for step_order ${step_order ?? 0}, variant A.`);
+            return toolError({ code: 'not_found', error: `No campaign step found for step_order ${step_order ?? 0}, variant A.` });
         // 2. Top-performing historical subjects
         let logQuery = db()
             .from('email_log')
@@ -320,12 +348,6 @@ export function registerAdvisorTools(server) {
             .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 });
@@ -354,7 +376,7 @@ Each subject should be distinct in approach (urgency, curiosity, benefit, social
             suggestions = JSON.parse(raw.replace(/```json?\n?|```/g, '').trim());
         }
         catch {
-            return txt(`Error: Failed to parse AI response. Raw: ${raw.slice(0, 200)}`);
+            return toolError({ code: 'internal_error', error: 'Failed to parse AI response.' });
         }
         // 5. Optionally create variants
         let variantsCreated;
@@ -404,9 +426,14 @@ Each subject should be distinct in approach (urgency, curiosity, benefit, social
         },
     }, async ({ site_id, days: daysParam }) => {
         const projectId = getProjectId();
+        const { data: site, error: siteError } = await advisorSite(site_id, projectId);
+        if (siteError)
+            return toolError(dbToolError(siteError));
+        if (!site)
+            return toolError({ code: 'not_found', error: 'Site not found' });
         const apiKey = process.env.ANTHROPIC_API_KEY;
         if (!apiKey)
-            return txt('Error: ANTHROPIC_API_KEY not configured.');
+            return toolError({ code: 'internal_error', 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
@@ -418,7 +445,8 @@ Each subject should be distinct in approach (urgency, curiosity, benefit, social
             .gte('created_at', since)
             .not('campaign_id', 'is', null));
         if (!logRows || logRows.length < 20) {
-            return j({
+            return toolError({
+                code: 'conflict',
                 error: 'insufficient_data',
                 message: `Only ${logRows?.length ?? 0} campaign emails found in the last ${days} days. Need at least 20 for meaningful analysis.`,
             });
@@ -440,18 +468,13 @@ Each subject should be distinct in approach (urgency, curiosity, benefit, social
         const topPerformers = ranked.slice(0, 10);
         const bottomPerformers = ranked.slice(-5);
         if (topPerformers.length < 3) {
-            return j({
+            return toolError({
+                code: 'conflict',
                 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 });
@@ -486,7 +509,7 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
             suggestions = JSON.parse(raw.replace(/```json?\n?|```/g, '').trim());
         }
         catch {
-            return txt(`Error: Failed to parse AI response. Raw: ${raw.slice(0, 300)}`);
+            return toolError({ code: 'internal_error', error: 'Failed to parse AI response.' });
         }
         return j({
             site: site?.name ?? site_id,
@@ -516,6 +539,19 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
         },
     }, async ({ site_id, segment_id, days: daysParam, metric }) => {
         const projectId = getProjectId();
+        const { data: site, error: siteError } = await advisorSite(site_id, projectId);
+        if (siteError)
+            return toolError(dbToolError(siteError));
+        if (!site)
+            return toolError({ code: 'not_found', error: 'Site not found' });
+        if (segment_id) {
+            const { data: segment, error } = await db()
+                .from('segments').select('id').eq('id', segment_id).eq('project_id', projectId).maybeSingle();
+            if (error)
+                return toolError(dbToolError(error));
+            if (!segment)
+                return toolError({ code: 'not_found', error: 'Segment not found' });
+        }
         const days = daysParam ?? 90;
         const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
         // 1. Get contact IDs for segment filter
@@ -545,7 +581,8 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
         }
         const rows = await readAllRows(query);
         if (!rows || rows.length < 30) {
-            return j({
+            return toolError({
+                code: 'conflict',
                 error: 'insufficient_data',
                 message: `Only ${rows?.length ?? 0} qualifying emails found in the last ${days} days. Need at least 30 for meaningful analysis.`,
                 coverage,
@@ -617,6 +654,11 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
         const dkimFailed = dkimValid === false;
         const dmarcValid = health?.dmarc_valid ?? null; // null = not checked yet (#3904)
         const dmarcFailed = dmarcValid === false;
+        const unchecked = [
+            ...(spfValid === null ? ['spf'] : []),
+            ...(dkimValid === null ? ['dkim'] : []),
+            ...(dmarcValid === null ? ['dmarc'] : []),
+        ];
         const warmupDay = health?.warmup_day ?? null;
         const warmupDailyLimit = health?.warmup_daily_limit ?? null;
         // 3. Fetch recent 7-day email_log stats
@@ -653,6 +695,8 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
             issues.push({ type: 'dns_invalid', severity: 'high', detail: `Missing DNS: ${spfFailed ? 'SPF' : ''}${spfFailed && dkimFailed ? ' + ' : ''}${dkimFailed ? 'DKIM' : ''}` });
         if (dmarcFailed)
             issues.push({ type: 'no_dmarc', severity: 'medium', detail: 'DMARC record missing or invalid' });
+        if (unchecked.length)
+            issues.push({ type: 'dns_unchecked', severity: 'medium', detail: `SPF/DKIM/DMARC not checked yet: ${unchecked.map(record => record.toUpperCase()).join(', ')}` });
         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` });
         }
@@ -750,6 +794,7 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
         return j({
             site: { id: site.id, slug: site.slug, domain: site.sending_domain },
             health_score: totalSent === 0 ? null : healthScore,
+            health_score_basis: { unchecked },
             ...(totalSent === 0 ? { health_score_reason: 'no_send_data', reason: 'no_send_data' } : {}),
             recent_7d: {
                 total_sent: totalSent,
@@ -766,11 +811,11 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
             new_suppressions_7d: newSuppressions ?? 0,
             issues,
             plan: {
-                immediate: immediate.length > 0 ? immediate : ['No immediate action required'],
+                immediate: immediate.length > 0 ? immediate : [unchecked.length ? 'Run a DNS check for the sending domain (SPF/DKIM/DMARC are not verified yet)' : 'No immediate action required'],
                 short_term: shortTerm.length > 0 ? shortTerm : ['Continue current sending practices'],
                 monitoring,
             },
-            ...(issues.some(issue => issue.type !== 'no_recent_sends') ? { estimated_recovery: estimatedRecovery } : {}),
+            ...(issues.some(issue => issue.type !== 'no_recent_sends' && issue.type !== 'dns_unchecked') ? { estimated_recovery: estimatedRecovery } : {}),
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.181",
+  "version": "1.0.182",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",