@sendinel/mcp-server 1.0.0

package/build/server.js

@@ -0,0 +1,235 @@
+import { registerAnalyticsTools } from './tools/analytics.js';
+import { registerCampaignTools } from './tools/campaigns.js';
+import { registerContactTools } from './tools/contacts.js';
+import { registerDraftTools } from './tools/drafts.js';
+import { registerGdprTools } from './tools/gdpr.js';
+import { registerSegmentTools } from './tools/segments.js';
+import { registerSiteTools } from './tools/sites.js';
+import { registerAbTestingTools } from './tools/ab-testing.js';
+import { registerAdvisorTools } from './tools/advisor.js';
+import { registerWebhookTools } from './tools/webhooks.js';
+import { registerApprovalTools } from './tools/approvals.js';
+import { registerAutomationTools } from './tools/automations.js';
+import { registerTemplateTools } from './tools/templates.js';
+import { registerDeliveryOpsTools } from './tools/delivery-ops.js';
+import { registerCompoundTools } from './tools/compound.js';
+import { registerDataTools } from './tools/data.js';
+import { registerContentTools } from './tools/content.js';
+import { registerWarmupTools } from './tools/warmup.js';
+import { registerFormTools } from './tools/forms.js';
+import { registerOrgTools } from './tools/org.js';
+import { registerSmsTools } from './tools/sms.js';
+import { registerSocialPostTools } from './tools/social-posts.js';
+import { registerDataProposalTools } from './tools/data-proposals.js';
+const GROUP_REGISTRY = {
+    analytics: registerAnalyticsTools,
+    campaigns: registerCampaignTools,
+    contacts: registerContactTools,
+    segments: registerSegmentTools,
+    drafts: registerDraftTools,
+    sites: registerSiteTools,
+    gdpr: registerGdprTools,
+    'ab-testing': registerAbTestingTools,
+    advisor: registerAdvisorTools,
+    webhooks: registerWebhookTools,
+    approvals: registerApprovalTools,
+    automations: registerAutomationTools,
+    templates: registerTemplateTools,
+    'delivery-ops': registerDeliveryOpsTools,
+    compound: registerCompoundTools,
+    data: registerDataTools,
+    content: registerContentTools,
+    warmup: registerWarmupTools,
+    forms: registerFormTools,
+    org: registerOrgTools,
+    sms: registerSmsTools,
+    'social-posts': registerSocialPostTools,
+    'data-proposals': registerDataProposalTools,
+};
+export const ALL_TOOL_GROUPS = Object.keys(GROUP_REGISTRY);
+// ── Scope enforcement ─────────────────────────────────────────────────────
+// Maps tool names to required scope. Mirrors dashboard's WRITE_TOOLS/ADMIN_TOOLS.
+const WRITE_TOOLS = new Set([
+    'add_subscriber', 'import_subscribers', 'update_subscriber',
+    'enrich_subscriber',
+    'create_campaign', 'update_campaign', 'delete_campaign', 'add_campaign_step', 'update_campaign_status',
+    'list_campaign_steps', 'update_campaign_step', 'delete_campaign_step',
+    'enroll_contact', 'enroll_segment', 'get_enrollment_status', 'clone_campaign', 'generate_email',
+    'create_social_campaign', 'schedule_social_post',
+    'create_social_post', 'update_social_post', 'delete_social_post',
+    'create_draft', 'approve_draft', 'reject_draft',
+    'create_site', 'create_sender', 'update_site',
+    'create_template', 'update_template', 'delete_template', 'translate_template',
+    'delete_subscriber_data', 'identify_inactive', 'set_subscriber_tags',
+    'update_hygiene_config',
+    'create_segment', 'update_segment', 'delete_segment', 'create_segment_nl',
+    'launch_campaign', 'merge_subscribers', 'create_campaign_with_content',
+    'send_test_email', 'send_transactional', 'subscribe_webhook', 'update_webhook_subscription',
+    'create_ab_test', 'promote_ab_winner', 'optimize_subject_lines',
+    'unsubscribe_subscriber', 'add_suppression', 'remove_suppression',
+    'trigger_automation', 'enroll_automation',
+    'update_scoring_rules', 'register_domain',
+    'update_warmup_schedule', 'pause_warmup', 'resume_warmup',
+    'create_form', 'invite_team_member',
+    'create_api_key', 'revoke_api_key', 'mark_notifications_read',
+    'migrate_campaigns_from', 'start_platform_migration',
+    'create_content_block', 'delete_content_block', 'trigger_content_pipeline',
+    'run_list_hygiene', 'run_portfolio_analysis',
+    'abuse_monitor_override',
+    'send_sms', 'send_sms_campaign', 'set_contact_sms_consent',
+    'setup_campaign_from_brief', 'create_template_from_brief', 'diagnose_delivery_issue', 'onboard_new_site',
+    'connect_platform', 'disconnect_platform', 'configure_platform_trigger',
+    'update_brand_voice', 'promote_draft_to_campaign',
+    'propose_campaign_from_data', 'approve_data_proposal',
+]);
+const ADMIN_TOOLS = new Set([
+    'delete_subscriber_data', 'list_deletion_log',
+    'unsubscribe_subscriber', 'add_suppression', 'remove_suppression',
+    'create_site', 'update_site',
+    'delete_template', 'register_domain', 'onboard_new_site',
+    'create_api_key', 'revoke_api_key', 'invite_team_member',
+    'connect_platform', 'disconnect_platform', 'configure_platform_trigger',
+    'abuse_monitor_override',
+    'tenant_export_full',
+    'identify_inactive', 'delete_segment',
+    'merge_subscribers', 'delete_webhook_subscription',
+]);
+const SCOPE_HIERARCHY = { read: 1, write: 2, admin: 3 };
+export function getRequiredScope(name) {
+    if (ADMIN_TOOLS.has(name))
+        return 'admin';
+    if (WRITE_TOOLS.has(name))
+        return 'write';
+    return 'read';
+}
+function scopeAllows(keyScopes, required) {
+    const requiredLevel = SCOPE_HIERARCHY[required] ?? 99;
+    return keyScopes.some((s) => (SCOPE_HIERARCHY[s] ?? 0) >= requiredLevel);
+}
+/**
+ * Collects tool-name → group metadata from the same group registry used by
+ * registerAllTools(). Scope filtering and definition scanning are applied
+ * through the same proxy path as real MCP registration.
+ */
+export function getRegisteredToolGroups(options) {
+    const groups = options?.toolGroups === undefined
+        ? ALL_TOOL_GROUPS
+        : options.toolGroups;
+    const toolGroups = {};
+    let currentGroup = '';
+    const collector = {
+        registerTool(name, _config, _handler) {
+            toolGroups[name] = currentGroup;
+        },
+    };
+    const effectiveServer = createScopeProxy(collector, options?.scopes?.length ? options.scopes : null);
+    for (const group of groups) {
+        const register = GROUP_REGISTRY[group];
+        if (!register)
+            continue;
+        currentGroup = group;
+        register(effectiveServer);
+    }
+    return toolGroups;
+}
+const INJECTION_PATTERNS = [
+    // Direct prompt injection
+    { pattern: /ignore\s+(all\s+)?(previous|prior|above)\s+instructions?/i, label: 'ignore-instructions', severity: 'block' },
+    { pattern: /you\s+are\s+now\s+(in\s+)?(maintenance|developer|admin|god)\s+mode/i, label: 'mode-switch', severity: 'block' },
+    { pattern: /\bsystem\s*:/i, label: 'system-prefix', severity: 'block' },
+    { pattern: /act\s+as\s+(a\s+)?(different|new|another)\s+(ai|assistant|model)/i, label: 'persona-switch', severity: 'block' },
+    { pattern: /do\s+not\s+(tell|inform|mention)\s+(the\s+)?(user|human)/i, label: 'conceal-from-user', severity: 'block' },
+    { pattern: /before\s+respond(ing)?,?\s+(always\s+)?call/i, label: 'forced-tool-call', severity: 'block' },
+    // Exfiltration
+    { pattern: /\bfetch\s*\(/i, label: 'exfil-fetch', severity: 'block' },
+    { pattern: /https?:\/\//i, label: 'external-url', severity: 'warn' },
+    { pattern: /base64|btoa|atob/i, label: 'encoding-exfil', severity: 'warn' },
+    // Hidden Unicode (zero-width, directional overrides, BOM)
+    { pattern: /[\u200b-\u200f\u202a-\u202e\u2060-\u206f\u2066-\u2069\ufeff]/u, label: 'hidden-unicode', severity: 'block' },
+];
+// Tool names must be lowercase snake_case identifiers, max 64 chars
+const VALID_TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+// Pattern labels that are downgraded from block→warn via env var, e.g.
+// MCP_TOOL_SCAN_ALLOWLIST=external-url
+const SCAN_ALLOWLIST = new Set((process.env.MCP_TOOL_SCAN_ALLOWLIST ?? '').split(',').map(s => s.trim()).filter(Boolean));
+// MCP_TOOL_SCAN_MODE=block (default) | warn | off
+const SCAN_MODE = (process.env.MCP_TOOL_SCAN_MODE ?? 'block');
+function scanToolDefinition(name, config) {
+    if (SCAN_MODE === 'off')
+        return [];
+    const findings = [];
+    // Name format (typosquatting / embedded injection)
+    if (!VALID_TOOL_NAME.test(name)) {
+        findings.push({ field: 'name', pattern: 'invalid-format', severity: 'warn', match: name.slice(0, 80) });
+    }
+    for (const { pattern, label, severity } of INJECTION_PATTERNS) {
+        if (pattern.test(name)) {
+            const effective = SCAN_ALLOWLIST.has(label) ? 'warn' : severity;
+            findings.push({ field: 'name', pattern: label, severity: effective, match: name.slice(0, 80) });
+        }
+    }
+    // Description
+    const desc = config?.description ?? '';
+    for (const { pattern, label, severity } of INJECTION_PATTERNS) {
+        if (pattern.test(desc)) {
+            const effective = SCAN_ALLOWLIST.has(label) ? 'warn' : severity;
+            findings.push({ field: 'description', pattern: label, severity: effective, match: desc.slice(0, 120) });
+        }
+    }
+    return findings;
+}
+/**
+ * Creates a Proxy around McpServer that intercepts registerTool calls
+ * and wraps handlers with scope enforcement.
+ */
+// scopes=null means no scope restriction (all tools allowed) but scan still runs.
+function createScopeProxy(server, scopes) {
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === 'registerTool') {
+                return (name, config, handler) => {
+                    // ── Tool definition scan (prompt injection / poisoning defense) ──
+                    // Always runs, regardless of whether scope enforcement is active.
+                    const findings = scanToolDefinition(name, config);
+                    if (findings.length > 0) {
+                        const wouldBlock = SCAN_MODE === 'block' && findings.some(f => f.severity === 'block');
+                        const level = wouldBlock ? 'BLOCK' : 'WARN';
+                        console.error(`[MCP SCAN] ${level} tool="${name}" findings=${JSON.stringify(findings)}`);
+                        if (wouldBlock)
+                            return; // omit from tool list entirely
+                    }
+                    // ── Scope enforcement (only when scopes are provided) ─────────────
+                    if (scopes !== null) {
+                        const required = getRequiredScope(name);
+                        if (!scopeAllows(scopes, required)) {
+                            // Don't register tools the key can't access — they won't appear in tool list
+                            return;
+                        }
+                        // Wrap handler with runtime scope check (defense in depth)
+                        const guardedHandler = (...args) => {
+                            if (!scopeAllows(scopes, required)) {
+                                return { content: [{ type: 'text', text: `Forbidden: this action requires "${required}" scope.` }] };
+                            }
+                            return handler(...args);
+                        };
+                        return target.registerTool(name, config, guardedHandler);
+                    }
+                    return target.registerTool(name, config, handler);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+export function registerAllTools(server, options) {
+    const groups = options?.toolGroups === undefined
+        ? ALL_TOOL_GROUPS
+        : options.toolGroups;
+    // Always wrap — scanner runs for every caller, scope enforcement only when scopes provided
+    const effectiveServer = createScopeProxy(server, options?.scopes?.length ? options.scopes : null);
+    for (const group of groups) {
+        const register = GROUP_REGISTRY[group];
+        if (register)
+            register(effectiveServer);
+    }
+}

package/build/tools/ab-testing.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAbTestingTools(server: McpServer): void;

package/build/tools/ab-testing.js

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+import { db } from '../db.js';
+import { getProjectId } from '../project.js';
+const txt = (text) => ({ content: [{ type: 'text', text }] });
+const j = (data) => txt(JSON.stringify(data, null, 2));
+export function registerAbTestingTools(server) {
+    server.registerTool('create_ab_test', {
+        description: 'Create an A/B test for a campaign step. Requires at least 2 variant steps (add via add_campaign_step with variant_label). Returns the test config for review.',
+        inputSchema: {
+            campaign_id: z.string().uuid(),
+            step_order: z.number().int().min(0).optional().default(0).describe('Which step to test (default: 0, the first email)'),
+            name: z.string().min(1).describe('Test name, e.g. "Subject line urgency test"'),
+            metric: z.enum(['open_rate', 'click_rate']).optional().default('open_rate'),
+            split_ratio: z.number().min(0.1).max(0.9).optional().default(0.5).describe('Fraction of sends to variant A (default: 0.5)'),
+            min_sample_size: z.number().int().min(10).optional().default(100).describe('Minimum sends per variant before testing significance'),
+            confidence_level: z.number().min(0.8).max(0.99).optional().default(0.95),
+            auto_promote: z.boolean().optional().default(false).describe('Automatically promote winner when significant'),
+        },
+    }, async ({ campaign_id, step_order, name, metric, split_ratio, min_sample_size, confidence_level, auto_promote }) => {
+        const projectId = getProjectId();
+        // Validate campaign exists
+        const { data: campaign, error: campErr } = await db()
+            .from('campaigns')
+            .select('id, name, status')
+            .eq('id', campaign_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (campErr || !campaign)
+            return txt('Error: Campaign not found');
+        // Check variant steps exist
+        const { data: steps } = await db()
+            .from('campaign_steps')
+            .select('id, variant_label, subject')
+            .eq('campaign_id', campaign_id)
+            .eq('step_order', step_order ?? 0);
+        const variantLabels = (steps ?? []).map((s) => s.variant_label);
+        if (variantLabels.length < 2) {
+            return txt(`Error: Need at least 2 variant steps for step_order ${step_order ?? 0}. Found: [${variantLabels.join(', ')}]. Add more variants via add_campaign_step with variant_label parameter.`);
+        }
+        // Check no existing test for this step
+        const { data: existing } = await db()
+            .from('ab_tests')
+            .select('id')
+            .eq('campaign_id', campaign_id)
+            .eq('step_order', step_order ?? 0)
+            .maybeSingle();
+        if (existing)
+            return txt(`Error: A/B test already exists for campaign step ${step_order ?? 0}. Test ID: ${existing.id}`);
+        const { data: test, error: createErr } = await db()
+            .from('ab_tests')
+            .insert({
+            project_id: projectId,
+            campaign_id,
+            step_order: step_order ?? 0,
+            name,
+            metric: metric ?? 'open_rate',
+            variants: variantLabels.sort(),
+            split_ratio: split_ratio ?? 0.5,
+            min_sample_size: min_sample_size ?? 100,
+            confidence_level: confidence_level ?? 0.95,
+            auto_promote: auto_promote ?? false,
+            status: 'draft',
+        })
+            .select()
+            .single();
+        if (createErr)
+            return txt(`Error: ${createErr.message}`);
+        return j({
+            ...test,
+            variant_steps: steps,
+            message: `A/B test "${name}" created. Update status to 'running' when the campaign is activated, or it will start automatically when sends begin. Variants: ${variantLabels.join(' vs ')}.`,
+        });
+    });
+    server.registerTool('list_ab_tests', {
+        description: 'List A/B tests, optionally filtered by campaign or status',
+        inputSchema: {
+            campaign_id: z.string().uuid().optional(),
+            status: z.enum(['draft', 'running', 'significant', 'completed']).optional(),
+            limit: z.number().int().min(1).max(50).optional().default(25),
+        },
+    }, async ({ campaign_id, status, limit }) => {
+        let q = db()
+            .from('ab_tests')
+            .select('*')
+            .eq('project_id', getProjectId())
+            .order('created_at', { ascending: false })
+            .limit(limit ?? 25);
+        if (campaign_id)
+            q = q.eq('campaign_id', campaign_id);
+        if (status)
+            q = q.eq('status', status);
+        const { data, error } = await q;
+        if (error)
+            return txt(`Error: ${error.message}`);
+        return j(data);
+    });
+    server.registerTool('check_ab_significance', {
+        description: 'Check statistical significance of an A/B test. Uses a two-proportion z-test. Returns per-variant rates, z-score, p-value, and whether the result is significant at the configured confidence level.',
+        inputSchema: {
+            test_id: z.string().uuid(),
+        },
+    }, async ({ test_id }) => {
+        // First, ensure the test is running (auto-start if campaign is active)
+        const { data: test } = await db()
+            .from('ab_tests')
+            .select('id, status, campaign_id')
+            .eq('id', test_id)
+            .eq('project_id', getProjectId())
+            .maybeSingle();
+        if (!test)
+            return txt('Error: Test not found');
+        if (test.status === 'draft') {
+            // Auto-start if campaign is active
+            const { data: camp } = await db()
+                .from('campaigns')
+                .select('status')
+                .eq('id', test.campaign_id)
+                .maybeSingle();
+            if (camp?.status === 'active') {
+                await db()
+                    .from('ab_tests')
+                    .update({ status: 'running' })
+                    .eq('id', test_id);
+            }
+        }
+        const { data, error } = await db()
+            .schema('email')
+            .rpc('check_ab_significance', { p_test_id: test_id });
+        if (error)
+            return txt(`Error: ${error.message}`);
+        return j(data);
+    });
+    server.registerTool('promote_ab_winner', {
+        description: 'End an A/B test and keep only the winning variant. Requires confirmation (two-call pattern). Deletes the losing variant step(s) from campaign_steps.',
+        inputSchema: {
+            test_id: z.string().uuid(),
+            winner: z.string().optional().describe('Override winner variant label (default: use statistically determined winner)'),
+            confirmed: z.boolean().optional().describe('Set true to execute after previewing'),
+        },
+    }, async ({ test_id, winner, confirmed }) => {
+        const projectId = getProjectId();
+        const { data: test, error: testErr } = await db()
+            .from('ab_tests')
+            .select('*')
+            .eq('id', test_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (testErr || !test)
+            return txt('Error: Test not found');
+        const winnerLabel = winner ?? test.winner;
+        if (!winnerLabel) {
+            return txt('Error: No winner determined yet. Run check_ab_significance first, or specify a winner manually.');
+        }
+        if (!test.variants.includes(winnerLabel)) {
+            return txt(`Error: "${winnerLabel}" is not a valid variant. Options: ${test.variants.join(', ')}`);
+        }
+        const losingVariants = test.variants.filter((v) => v !== winnerLabel);
+        // Get step details for preview
+        const { data: steps } = await db()
+            .from('campaign_steps')
+            .select('id, variant_label, subject')
+            .eq('campaign_id', test.campaign_id)
+            .eq('step_order', test.step_order);
+        const winnerStep = (steps ?? []).find((s) => s.variant_label === winnerLabel);
+        const loserSteps = (steps ?? []).filter((s) => losingVariants.includes(s.variant_label));
+        if (!confirmed) {
+            return j({
+                confirmation_required: true,
+                test_id,
+                test_name: test.name,
+                winner: winnerLabel,
+                winner_subject: winnerStep?.subject,
+                losing_variants: loserSteps.map((s) => ({
+                    variant: s.variant_label,
+                    subject: s.subject,
+                })),
+                message: `Will promote variant "${winnerLabel}" and delete ${loserSteps.length} losing variant(s). Call again with confirmed: true to execute.`,
+            });
+        }
+        // Delete losing variant steps
+        for (const loser of loserSteps) {
+            await db()
+                .from('campaign_steps')
+                .delete()
+                .eq('id', loser.id);
+        }
+        // Mark test completed
+        await db()
+            .from('ab_tests')
+            .update({
+            status: 'completed',
+            winner: winnerLabel,
+            decided_at: new Date().toISOString(),
+        })
+            .eq('id', test_id);
+        return j({
+            test_id,
+            status: 'completed',
+            winner: winnerLabel,
+            deleted_variants: losingVariants,
+            message: `A/B test "${test.name}" completed. Variant "${winnerLabel}" promoted, ${loserSteps.length} losing step(s) removed.`,
+        });
+    });
+}

package/build/tools/advisor.d.ts

@@ -0,0 +1,23 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface PeriodMetrics {
+    sent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    bounced: number;
+    complained: number;
+    open_rate: number;
+    click_rate: number;
+    bounce_rate: number;
+    complaint_rate: number;
+}
+export declare function computeMetrics(rows: any[]): PeriodMetrics;
+interface TimeBucket {
+    label: string;
+    sends: number;
+    engagements: number;
+    rate: number;
+}
+export declare function buildTimeBuckets(rows: any[], groupBy: 'hour' | 'day', metric: string): TimeBucket[];
+export declare function registerAdvisorTools(server: McpServer): void;
+export {};