@sendinel/mcp-server 1.0.3 → 1.0.5

package/build/tools/analytics.js

@@ -147,8 +147,85 @@ function distinctEventCount(events, eventType, logIds) {
         .filter(event => event.event_type === eventType && event.email_log_id && logIds.has(event.email_log_id))
         .map(event => event.email_log_id)).size;
 }
+function isTrueConversionEvent(event) {
+    const normalized = (event ?? '').trim().toLowerCase().replace(/[\s-]+/g, '_');
+    if (!normalized)
+        return false;
+    return !['open', 'opened', 'email_open', 'click', 'clicked', 'email_click', 'page_view', 'view', 'impression'].includes(normalized);
+}
+function buildTrueConversionAnalytics(params) {
+    const sent = params.logs.length;
+    const delivered = params.logs.filter(row => ['delivered', 'opened', 'clicked'].includes(row.status)).length;
+    const trueRows = params.attributionRows.filter(row => isTrueConversionEvent(row.conversion_event));
+    const campaignDenominators = new Map();
+    for (const row of params.logs) {
+        if (typeof row.campaign_id !== 'string')
+            continue;
+        campaignDenominators.set(row.campaign_id, (campaignDenominators.get(row.campaign_id) ?? 0) + 1);
+    }
+    const byEvent = new Map();
+    const byVariant = new Map();
+    let totalRevenue = 0;
+    for (const row of trueRows) {
+        const revenue = Number(row.revenue_amount ?? 0) || 0;
+        totalRevenue += revenue;
+        const event = row.conversion_event?.trim() || 'conversion';
+        const eventStats = byEvent.get(event) ?? { conversion_event: event, count: 0, revenue: 0 };
+        eventStats.count += 1;
+        eventStats.revenue += revenue;
+        byEvent.set(event, eventStats);
+        const variant = row.utm_content?.trim() || '(none)';
+        const variantKey = `${row.campaign_id ?? '(none)'}:${variant}`;
+        const variantStats = byVariant.get(variantKey) ?? { variant, campaign_id: row.campaign_id ?? null, count: 0, revenue: 0 };
+        variantStats.count += 1;
+        variantStats.revenue += revenue;
+        byVariant.set(variantKey, variantStats);
+    }
+    const percentOf = (count, denominator) => denominator > 0 ? `${((count / denominator) * 100).toFixed(1)}%` : 'N/A';
+    const stage = (name, count, prior) => ({
+        stage: name,
+        count,
+        rate_from_sent: percentOf(count, sent),
+        rate_from_previous: prior == null ? '100.0%' : percentOf(count, prior),
+        drop_off_from_previous: prior == null ? 0 : Math.max(0, prior - count),
+    });
+    return {
+        definition: 'revenue_attribution rows excluding open/click/page-view vanity events',
+        true_conversions: trueRows.length,
+        true_conversion_rate: percentOf(trueRows.length, sent),
+        revenue: Number(totalRevenue.toFixed(2)),
+        by_event: Array.from(byEvent.values())
+            .map(row => ({ ...row, revenue: Number(row.revenue.toFixed(2)), true_conversion_rate: percentOf(row.count, sent) }))
+            .sort((a, b) => b.count - a.count),
+        funnel: [
+            stage('sent', sent, null),
+            stage('delivered', delivered, sent),
+            stage('opened', params.opened, delivered),
+            stage('clicked', params.clicked, params.opened),
+            stage('true_conversion', trueRows.length, params.clicked || params.opened || delivered),
+        ],
+        by_variant: Array.from(byVariant.values())
+            .map(row => {
+            const denominator = row.campaign_id ? (campaignDenominators.get(row.campaign_id) ?? sent) : sent;
+            return {
+                ...row,
+                revenue: Number(row.revenue.toFixed(2)),
+                denominator,
+                true_conversion_rate: percentOf(row.count, denominator),
+            };
+        })
+            .sort((a, b) => b.count - a.count || b.revenue - a.revenue),
+    };
+}
 export function registerAnalyticsTools(server) {
     server.registerTool('list_event_log', {
+        title: 'List Event Log',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List received API event tracking calls with optional filters.',
         inputSchema: {
             event_name: z.string().optional(),
@@ -177,6 +254,13 @@ export function registerAnalyticsTools(server) {
         return j({ events: data ?? [] });
     });
     server.registerTool('get_portfolio_analytics', {
+        title: 'Get Portfolio Analytics',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Get cross-site analytics totals and per-site breakdown.',
         inputSchema: { period_days: z.number().int().min(1).max(365).optional().default(30) },
     }, async ({ period_days = 30 }) => {
@@ -197,6 +281,13 @@ export function registerAnalyticsTools(server) {
         });
     });
     server.registerTool('list_projects', {
+        title: 'List Projects',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List all projects accessible to this API key. Returns project ID, name, plan, and associated organization. Useful for orchestrators managing multiple products through a single Sendinel account.',
         inputSchema: {},
     }, async () => {
@@ -238,6 +329,13 @@ export function registerAnalyticsTools(server) {
         });
     });
     server.registerTool('get_sites', {
+        title: 'Get Sites',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List all active Sendinel sites',
         inputSchema: {},
     }, async () => {
@@ -252,6 +350,13 @@ export function registerAnalyticsTools(server) {
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('get_stats', {
+        title: 'Get Stats',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Aggregate email metrics for a site over a date range. Returns sent, delivered, bounce/complaint rates, Sender Health Score (0–100), send volume by day, list growth rate, inactive subscriber percentage, and open/click rates when tracking is enabled.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site UUID'),
@@ -338,6 +443,13 @@ export function registerAnalyticsTools(server) {
         return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
     });
     server.registerTool('get_domain_health', {
+        title: 'Get Domain Health',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: 'SPF/DKIM/DMARC status and warmup progress for a site',
         inputSchema: {
             site_id: z.string().uuid().describe('Site UUID'),
@@ -355,6 +467,13 @@ export function registerAnalyticsTools(server) {
         return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('get_engagement_insights', {
+        title: 'Get Engagement Insights',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Get engagement scoring summary: lifecycle distribution, score buckets, top engaged contacts, at-risk contacts, and never-engaged counts. Use this data to recommend re-engagement campaigns, identify high-value contacts, or suggest list hygiene actions.',
         inputSchema: {
             site_id: z.string().uuid().optional().describe('Optional site UUID for site-specific tracking settings and engagement anomaly analysis'),
@@ -447,6 +566,13 @@ export function registerAnalyticsTools(server) {
                     }, null, 2) }] };
     });
     server.registerTool('deliverability_check', {
+        title: 'Deliverability Check',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: 'Run a deliverability check for a site: DNS records (SPF/DKIM/DMARC), warmup status, bounce/complaint rates, and risk assessment',
         inputSchema: {
             site_id: z.string().uuid(),
@@ -601,6 +727,13 @@ export function registerAnalyticsTools(server) {
         });
     });
     server.registerTool('performance_report', {
+        title: 'Performance Report',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Generate a performance report: delivery/open/click rates, best send times, trends. Optionally group by campaign, site, company, day, or week.',
         inputSchema: {
             days: z.number().int().min(1).max(365).optional().describe('Lookback period in days, default 30'),
@@ -626,6 +759,20 @@ export function registerAnalyticsTools(server) {
         const rows = logs ?? [];
         if (!rows.length)
             return j({ message: `No email activity in the last ${days} days.`, total: 0 });
+        let attributionQuery = db()
+            .from('revenue_attribution')
+            .select('campaign_id, conversion_event, utm_content, revenue_amount')
+            .eq('project_id', projectId)
+            .gte('converted_at', since);
+        if (campaign_id)
+            attributionQuery = attributionQuery.eq('campaign_id', campaign_id);
+        const { data: attributionRows, error: attributionError } = await attributionQuery;
+        if (attributionError)
+            return txt(`Error: ${attributionError.message}`);
+        const campaignIdsInScope = new Set(rows.map((row) => typeof row.campaign_id === 'string' ? row.campaign_id : null).filter(Boolean));
+        const scopedAttributionRows = site_id
+            ? (attributionRows ?? []).filter((row) => row.campaign_id && campaignIdsInScope.has(row.campaign_id))
+            : (attributionRows ?? []);
         const computeMetrics = (set) => {
             const total = set.length;
             const delivered = set.filter(r => ['delivered', 'opened', 'clicked'].includes(r.status)).length;
@@ -644,6 +791,12 @@ export function registerAnalyticsTools(server) {
             };
         };
         const overall = computeMetrics(rows);
+        const trueConversionAnalytics = buildTrueConversionAnalytics({
+            logs: rows,
+            attributionRows: scopedAttributionRows,
+            opened: parseInt(String(overall.opened), 10) || 0,
+            clicked: parseInt(String(overall.clicked), 10) || 0,
+        });
         const hourBuckets = {};
         rows.forEach((r) => {
             if (!r.sent_at)
@@ -744,6 +897,7 @@ export function registerAnalyticsTools(server) {
         return j({
             period: `Last ${days} days`,
             overall,
+            true_conversion_analytics: trueConversionAnalytics,
             best_send_times_utc: bestHours,
             trend_vs_prior_period: trend,
             ...(grouped ? { [`by_${group_by}`]: grouped } : {}),
@@ -751,6 +905,13 @@ export function registerAnalyticsTools(server) {
     });
     // ── Cross-project analytics ─────────────────────────────────────────────
     server.registerTool('get_portfolio_stats', {
+        title: 'Get Portfolio Stats',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Aggregate email metrics across all projects in your organization. Returns per-project and combined totals for the specified period. Useful for orchestrators managing multiple products.',
         inputSchema: {
             days: z.number().int().min(1).max(90).optional().default(30).describe('Lookback period in days (default: 30)'),
@@ -843,6 +1004,13 @@ export function registerAnalyticsTools(server) {
         });
     });
     server.registerTool('abuse_monitor_status', {
+        title: 'Abuse Monitor Status',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Return per-tenant abuse monitor metrics for a site, including complaint rate and pause level.',
         inputSchema: {
             siteId: z.string().uuid(),
@@ -880,6 +1048,13 @@ export function registerAnalyticsTools(server) {
         });
     });
     server.registerTool('abuse_monitor_override', {
+        title: 'Abuse Monitor Override',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Create a temporary abuse monitor override for a paused site. Overrides expire automatically and are capped at 72 hours.',
         inputSchema: {
             siteId: z.string().uuid(),
@@ -927,6 +1102,13 @@ export function registerAnalyticsTools(server) {
         });
     });
     server.registerTool('get_site_insights', {
+        title: 'Get Site Insights',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Get pre-computed AI insights for a site — anomalies, deliverability alerts, send-time recommendations, and attribution summaries. Call this before making campaign decisions to check for active warnings.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site UUID'),
@@ -960,6 +1142,13 @@ export function registerAnalyticsTools(server) {
         return j((data ?? []).sort((a, b) => (rank[a.severity] ?? 9) - (rank[b.severity] ?? 9)));
     });
     server.registerTool('create_social_campaign', {
+        title: 'Create Social Campaign',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: 'Create a social media campaign with a UTM-tracked link. Returns the tracked URL to paste into the social post.',
         inputSchema: {
             name: z.string(),
@@ -993,6 +1182,13 @@ export function registerAnalyticsTools(server) {
         return j({ id: data.id, tracked_url: data.tracked_url, campaign: data });
     });
     server.registerTool('list_social_campaigns', {
+        title: 'List Social Campaigns',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List social campaigns with their signup attribution and manual metrics. Use to compare channel performance.',
         inputSchema: {
             site_id: z.string().uuid().optional(),
@@ -1016,6 +1212,13 @@ export function registerAnalyticsTools(server) {
         return j({ campaigns: data ?? [] });
     });
     server.registerTool('schedule_social_post', {
+        title: 'Schedule Social Post',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         description: 'Schedule a social campaign post via a connected BYO publisher (UploadPost, Buffer). Returns publisherPostId on success.',
         inputSchema: {
             campaign_id: z.string().uuid().describe('UUID of the social campaign in Sendinel'),

package/build/tools/approvals.js

@@ -6,6 +6,13 @@ const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 export function registerApprovalTools(server) {
     server.registerTool('check_approval', {
+        title: 'Check Approval',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'Check the status of a pending action approval. Use this to poll after requesting an action that requires human approval. Returns approved/pending/rejected/expired.',
         inputSchema: {
             approval_id: z.string().uuid().describe('The approval ID returned by the original tool call'),
@@ -15,12 +22,19 @@ export function registerApprovalTools(server) {
         return j(result);
     });
     server.registerTool('list_pending_approvals', {
+        title: 'List Pending Approvals',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: 'List all pending approval requests for this project. Shows what actions are waiting for human approval.',
         inputSchema: {},
     }, async () => {
         const { data, error } = await db()
             .from('action_approvals')
-            .select('id, action, tier, summary, status, requested_at, expires_at')
+            .select('id, action, tier, channel, summary, status, requested_at, expires_at')
             .eq('project_id', getProjectId())
             .eq('status', 'pending')
             .order('requested_at', { ascending: false })