@sendinel/mcp-server 1.0.9 → 1.0.11

package/build/tools/segments.js

@@ -3,160 +3,41 @@ import Anthropic from '@anthropic-ai/sdk';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
-function isSegmentRuleGroup(value) {
-    const node = value;
-    return !!node && (node.op === 'AND' || node.op === 'OR') && Array.isArray(node.conditions);
-}
-function normalizeSegmentRulesToTree(rules) {
-    const source = (rules ?? {});
-    if (isSegmentRuleGroup(source))
-        return source;
-    const conditions = [];
-    if (source.lifecycle_stage)
-        conditions.push({ field: 'lifecycle_stage', operator: 'eq', value: source.lifecycle_stage });
-    if (source.min_score !== undefined)
-        conditions.push({ field: 'engagement_score', operator: 'gte', value: source.min_score });
-    if (source.max_score !== undefined)
-        conditions.push({ field: 'engagement_score', operator: 'lte', value: source.max_score });
-    if (source.source)
-        conditions.push({ field: 'source', operator: 'eq', value: source.source });
-    if (source.subscribed_after)
-        conditions.push({ field: 'created_at', operator: 'on_or_after', value: source.subscribed_after });
-    if (source.subscribed_before)
-        conditions.push({ field: 'created_at', operator: 'on_or_before', value: source.subscribed_before });
-    if (source.has_opened === true)
-        conditions.push({ field: 'last_opened_at', operator: 'exists' });
-    if (source.has_opened === false)
-        conditions.push({ field: 'last_opened_at', operator: 'not_exists' });
-    if (source.has_clicked === true)
-        conditions.push({ field: 'last_clicked_at', operator: 'exists' });
-    if (source.has_clicked === false)
-        conditions.push({ field: 'last_clicked_at', operator: 'not_exists' });
-    if (source.tag)
-        conditions.push({ field: 'tags', operator: 'contains', value: source.tag });
-    if (source.custom_property) {
-        const idx = source.custom_property.indexOf('=');
-        if (idx > 0)
-            conditions.push({ field: `custom_properties.${source.custom_property.slice(0, idx)}`, operator: 'eq', value: source.custom_property.slice(idx + 1) });
-    }
-    if (source.payment) {
-        for (const [field, value] of Object.entries(source.payment)) {
-            if (value == null || value === '')
-                continue;
-            if (typeof value === 'object' && !Array.isArray(value)) {
-                const rule = value;
-                if (typeof rule.within_days === 'number') {
-                    conditions.push({ field: `payment.${field}`, operator: 'on_or_after', value: new Date().toISOString() });
-                    conditions.push({ field: `payment.${field}`, operator: 'on_or_before', value: addDaysIso(rule.within_days) });
-                }
-                if (rule.after)
-                    conditions.push({ field: `payment.${field}`, operator: 'on_or_after', value: rule.after });
-                if (rule.before)
-                    conditions.push({ field: `payment.${field}`, operator: 'on_or_before', value: rule.before });
-            }
-            else {
-                conditions.push({ field: `payment.${field}`, operator: 'eq', value });
-            }
-        }
-    }
-    return { op: 'AND', conditions, exclude_suppressed: source.exclude_suppressed, site_id: source.site_id };
-}
-function addDaysIso(days) {
-    return new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString();
-}
-function getComparableValue(contact, field) {
-    if (field.startsWith('custom_properties.')) {
-        return field.slice('custom_properties.'.length).split('.').reduce((acc, part) => acc == null ? undefined : acc[part], contact.custom_properties);
+import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, normalizeSegmentRulesToTree, } from '@sendinel/domain';
+async function loadFieldTypes(projectId) {
+    const client = db();
+    const scoped = typeof client.schema === 'function' ? client.schema('email') : client;
+    const { data, error } = await scoped
+        .from('custom_field_definitions')
+        .select('key, type, options')
+        .eq('project_id', projectId);
+    if (error) {
+        console.warn('[segments] custom field definition load failed:', error.message ?? error);
+        return {};
     }
-    if (field.startsWith('payment.')) {
-        return field.slice('payment.'.length).split('.').reduce((acc, part) => acc == null ? undefined : acc[part], contact.custom_properties?.payment);
-    }
-    return contact[field];
-}
-function compareValues(actual, operator, expected) {
-    if (operator === 'exists')
-        return actual !== null && actual !== undefined && actual !== '';
-    if (operator === 'not_exists')
-        return actual === null || actual === undefined || actual === '';
-    if (operator === 'contains')
-        return Array.isArray(actual) ? actual.map(String).includes(String(expected)) : typeof actual === 'string' && actual.includes(String(expected));
-    if (operator === 'eq')
-        return String(actual ?? '') === String(expected ?? '');
-    if (operator === 'neq')
-        return String(actual ?? '') !== String(expected ?? '');
-    const actualNumber = Number(actual);
-    const expectedNumber = Number(expected);
-    const numeric = Number.isFinite(actualNumber) && Number.isFinite(expectedNumber);
-    const left = numeric ? actualNumber : Date.parse(String(actual ?? ''));
-    const right = numeric ? expectedNumber : Date.parse(String(expected ?? ''));
-    if (!Number.isFinite(left) || !Number.isFinite(right))
-        return false;
-    if (operator === 'gt' || operator === 'after')
-        return left > right;
-    if (operator === 'gte' || operator === 'on_or_after')
-        return left >= right;
-    if (operator === 'lt' || operator === 'before')
-        return left < right;
-    if (operator === 'lte' || operator === 'on_or_before')
-        return left <= right;
-    return false;
-}
-function evaluateNode(contact, node) {
-    if (isSegmentRuleGroup(node)) {
-        if (!node.conditions.length)
-            return true;
-        return node.op === 'OR' ? node.conditions.some((child) => evaluateNode(contact, child)) : node.conditions.every((child) => evaluateNode(contact, child));
+    const fields = {};
+    for (const row of data ?? []) {
+        if (typeof row.key !== 'string' || typeof row.type !== 'string')
+            continue;
+        fields[row.key] = { type: row.type, options: Array.isArray(row.options) ? row.options : null };
     }
-    return compareValues(getComparableValue(contact, node.field), node.operator ?? 'eq', node.value);
+    return fields;
 }
 async function getSegmentContactIds(rules) {
     const projectId = getProjectId();
     const tree = normalizeSegmentRulesToTree(rules);
-    let q = db()
-        .from('subscribers')
-        .select('id, email, lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, tags, custom_properties')
-        .eq('project_id', projectId)
-        .eq('global_unsubscribed', false);
-    if (!isSegmentRuleGroup(rules)) {
-        if (rules.lifecycle_stage)
-            q = q.eq('lifecycle_stage', rules.lifecycle_stage);
-        q = applyPaymentRules(q, rules.payment);
-        if (rules.min_score !== undefined)
-            q = q.gte('engagement_score', rules.min_score);
-        if (rules.max_score !== undefined)
-            q = q.lte('engagement_score', rules.max_score);
-        if (rules.source)
-            q = q.eq('source', rules.source);
-        if (rules.subscribed_after)
-            q = q.gte('created_at', `${rules.subscribed_after}T00:00:00Z`);
-        if (rules.subscribed_before)
-            q = q.lte('created_at', `${rules.subscribed_before}T23:59:59Z`);
-        if (rules.has_opened === true)
-            q = q.not('last_opened_at', 'is', null);
-        if (rules.has_opened === false)
-            q = q.is('last_opened_at', null);
-        if (rules.has_clicked === true)
-            q = q.not('last_clicked_at', 'is', null);
-        if (rules.has_clicked === false)
-            q = q.is('last_clicked_at', null);
-        if (rules.tag)
-            q = q.contains('tags', [rules.tag]);
-    }
-    if (tree.site_id) {
-        const { data: subs } = await db()
-            .from('site_subscriptions')
-            .select('contact_id')
-            .eq('site_id', tree.site_id)
-            .eq('subscribed', true);
-        const siteIds = (subs ?? []).map((s) => s.contact_id);
-        if (!siteIds.length)
-            return [];
-        q = q.in('id', siteIds);
-    }
-    const { data, error } = await q;
+    const fieldTypes = rules.custom_property ? await loadFieldTypes(projectId) : {};
+    // Shared base query (#3084). This used to be hand-written here and omitted
+    // is_test / source_deleted_at / the cooled exclusion the dashboard applies,
+    // so the same stored segment counted differently through MCP.
+    const q = buildSegmentBaseQuery(db(), projectId);
+    const { query: filtered, siteContactIds } = await applySegmentRules(q, rules, db(), projectId, fieldTypes);
+    if (siteContactIds && siteContactIds.length === 0)
+        return [];
+    const { data, error } = await filtered;
     if (error || !data)
         return [];
-    let contacts = data.filter((contact) => evaluateNode(contact, tree));
+    const contacts = data.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
     let ids = contacts.map((c) => String(c.id));
     if (tree.exclude_suppressed !== false && ids.length > 0) {
         const { data: suppressed } = await db()
@@ -172,42 +53,6 @@ async function getSegmentContactIds(rules) {
     }
     return ids;
 }
-function applyPaymentRules(query, payment) {
-    if (!payment)
-        return query;
-    let q = query;
-    if (payment.plan)
-        q = q.contains('custom_properties', { payment: { plan: payment.plan } });
-    if (payment.mrr_cents !== undefined)
-        q = q.contains('custom_properties', { payment: { mrr_cents: payment.mrr_cents } });
-    if (payment.ltv_cents !== undefined)
-        q = q.contains('custom_properties', { payment: { ltv_cents: payment.ltv_cents } });
-    if (payment.subscription_status)
-        q = q.contains('custom_properties', { payment: { subscription_status: payment.subscription_status } });
-    q = applyPaymentDateRule(q, 'trial_ends_at', payment.trial_ends_at);
-    q = applyPaymentDateRule(q, 'churned_at', payment.churned_at);
-    q = applyPaymentDateRule(q, 'paid_at', payment.paid_at);
-    return q;
-}
-function applyPaymentDateRule(query, field, rule) {
-    if (!rule)
-        return query;
-    if (typeof rule === 'string') {
-        return query.contains('custom_properties', { payment: { [field]: rule } });
-    }
-    let q = query;
-    const column = `custom_properties->payment->>${field}`;
-    if (typeof rule.within_days === 'number') {
-        const start = new Date();
-        const end = new Date(start.getTime() + rule.within_days * 24 * 60 * 60 * 1000);
-        q = q.gte(column, start.toISOString()).lte(column, end.toISOString());
-    }
-    if (rule.after)
-        q = q.gte(column, rule.after);
-    if (rule.before)
-        q = q.lte(column, rule.before);
-    return q;
-}
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 export function registerSegmentTools(server) {
@@ -223,7 +68,7 @@ export function registerSegmentTools(server) {
         inputSchema: {
             name: z.string().min(1).describe('Segment name (unique per project)'),
             description: z.string().optional(),
-            rules: z.record(z.string(), z.unknown()).describe('Segment rule tree: {op:"AND"|"OR", conditions:[{field, operator, value}]} or legacy flat rules. Supported fields include lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, tags, custom_properties.<key>, payment.<key>.'),
+            rules: z.record(z.string(), z.unknown()).describe('Segment rule tree: {op:"AND"|"OR", conditions:[{field, operator, value}]} or legacy flat rules. Supported fields include lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.<key>. tag may be a plain string (one tag) or {values: string[], mode: "any"|"all"} to match several tags at once.'),
         },
     }, async ({ name, description, rules }) => {
         const { data, error } = await db()
@@ -233,6 +78,12 @@ export function registerSegmentTools(server) {
             .single();
         if (error)
             return txt(`Error: ${error.message}`);
+        // Count against the stored (normalized) tree, not the raw input: a tree skips
+        // applySegmentRules' SQL push-down and filters in JS, which is what list_segments
+        // does for this same segment a moment later. Pushing the flat rules down instead
+        // makes the two disagree wherever SQL and JS compare differently -- notably
+        // custom_property against a non-string JSONB value (boolean/number), where
+        // `@> {"k":"true"}` misses a stored `true` but String(actual)===String(expected) matches.
         const ids = await getSegmentContactIds(data.rules);
         return j({ ...data, estimated_contacts: ids.length });
     });
@@ -383,7 +234,7 @@ export function registerSegmentTools(server) {
         const resp = await anthropic.messages.create({
             model: getAnthropicModelId(),
             max_tokens: 512,
-            system: 'You translate natural language audience descriptions into a JSON segment rule tree. Return ONLY valid JSON. Format: {"op":"AND"|"OR","conditions":[conditionOrGroup],"exclude_suppressed":true}. Condition format: {"field": string, "operator":"eq|neq|gt|gte|lt|lte|contains|exists|not_exists|after|before|on_or_after|on_or_before","value": any}. Supported fields: lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, tags, custom_properties.<key>, payment.plan, payment.mrr_cents, payment.ltv_cents, payment.subscription_status, payment.trial_ends_at, payment.churned_at, payment.paid_at. Example: {"op":"AND","conditions":[{"field":"lifecycle_stage","operator":"eq","value":"trial"},{"field":"payment.trial_ends_at","operator":"on_or_before","value":"' + new Date(Date.now() + 7 * 86400000).toISOString() + '"}]}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
+            system: 'You translate natural language audience descriptions into a JSON segment rule tree. Return ONLY valid JSON. Format: {"op":"AND"|"OR","conditions":[conditionOrGroup],"exclude_suppressed":true}. Condition format: {"field": string, "operator":"eq|neq|gt|gte|lt|lte|contains|exists|not_exists|after|before|on_or_after|on_or_before","value": any}. Supported fields: lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.plan, payment.mrr_cents, payment.ltv_cents, payment.subscription_status, payment.trial_ends_at, payment.churned_at, payment.paid_at. Example: {"op":"AND","conditions":[{"field":"lifecycle_stage","operator":"eq","value":"trial"},{"field":"payment.trial_ends_at","operator":"on_or_before","value":"' + new Date(Date.now() + 7 * 86400000).toISOString() + '"}]}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
             messages: [{ role: 'user', content: description }],
         });
         const tb = resp.content.find((b) => b.type === 'text');

package/build/tools/signatures.d.ts

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

package/build/tools/signatures.js

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+import { db } from '../db.js';
+import { getProjectId } from '../project.js';
+import { logAudit } from '../audit.js';
+const txt = (text) => ({ content: [{ type: 'text', text }] });
+const j = (data) => txt(JSON.stringify(data, null, 2));
+const COLUMNS = 'id, site_id, name, html, is_default, created_at, updated_at';
+export function registerSignatureTools(server) {
+    server.registerTool('list_signatures', {
+        title: 'List Signatures',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'List project-scoped sending signature blocks, optionally filtered by site.',
+        inputSchema: { site_id: z.string().uuid().optional() },
+    }, async ({ site_id }) => {
+        let query = db()
+            .from('signature_blocks')
+            .select(COLUMNS)
+            .eq('project_id', getProjectId())
+            .order('is_default', { ascending: false })
+            .order('created_at', { ascending: true });
+        if (site_id)
+            query = query.eq('site_id', site_id);
+        const { data, error } = await query;
+        if (error)
+            return j({ error: error.message });
+        return j({ signatures: data ?? [], count: data?.length ?? 0 });
+    });
+    server.registerTool('create_signature', {
+        title: 'Create Signature',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: 'Create a signature block for a site. Setting it as default clears the existing default for that site.',
+        inputSchema: {
+            site_id: z.string().uuid(),
+            name: z.string().trim().min(1),
+            html: z.string().trim().min(1),
+            is_default: z.boolean().optional(),
+        },
+    }, async ({ site_id, name, html, is_default }) => {
+        const projectId = getProjectId();
+        const { data: site, error: siteError } = await db()
+            .from('sites')
+            .select('id')
+            .eq('id', site_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (siteError)
+            return j({ error: siteError.message });
+        if (!site)
+            return j({ error: 'Site not found', code: 'NOT_FOUND' });
+        if (is_default) {
+            const { error: clearError } = await db()
+                .from('signature_blocks')
+                .update({ is_default: false })
+                .eq('project_id', projectId)
+                .eq('site_id', site_id);
+            if (clearError)
+                return j({ error: clearError.message });
+        }
+        const { data, error } = await db()
+            .from('signature_blocks')
+            .insert({
+            project_id: projectId,
+            site_id,
+            name: name.trim(),
+            html: html.trim(),
+            is_default: is_default ?? false,
+        })
+            .select(COLUMNS)
+            .single();
+        if (error)
+            return j({ error: error.message });
+        await logAudit({
+            action: 'signature.created',
+            resourceType: 'signature',
+            resourceId: data.id,
+            details: { name: data.name, site_id: data.site_id, is_default: data.is_default, via: 'mcp' },
+        });
+        return j({ signature: data });
+    });
+    server.registerTool('update_signature', {
+        title: 'Update Signature',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Update a signature name, HTML, or default state. Setting it as default clears the other default for its site.',
+        inputSchema: {
+            id: z.string().uuid(),
+            name: z.string().trim().min(1).optional(),
+            html: z.string().trim().min(1).optional(),
+            is_default: z.boolean().optional(),
+        },
+    }, async ({ id, name, html, is_default }) => {
+        const projectId = getProjectId();
+        const { data: existing, error: existingError } = await db()
+            .from('signature_blocks')
+            .select('id, site_id')
+            .eq('id', id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (existingError)
+            return j({ error: existingError.message });
+        if (!existing)
+            return j({ error: 'Signature not found', code: 'NOT_FOUND' });
+        if (is_default) {
+            const { error: clearError } = await db()
+                .from('signature_blocks')
+                .update({ is_default: false })
+                .eq('project_id', projectId)
+                .eq('site_id', existing.site_id)
+                .neq('id', id);
+            if (clearError)
+                return j({ error: clearError.message });
+        }
+        const updates = { updated_at: new Date().toISOString() };
+        if (name !== undefined)
+            updates.name = name.trim();
+        if (html !== undefined)
+            updates.html = html.trim();
+        if (is_default !== undefined)
+            updates.is_default = is_default;
+        const { data, error } = await db()
+            .from('signature_blocks')
+            .update(updates)
+            .eq('id', id)
+            .eq('project_id', projectId)
+            .select(COLUMNS)
+            .single();
+        if (error)
+            return j({ error: error.message });
+        await logAudit({
+            action: 'signature.updated',
+            resourceType: 'signature',
+            resourceId: data.id,
+            details: { name: data.name, site_id: data.site_id, is_default: data.is_default, via: 'mcp' },
+        });
+        return j({ signature: data });
+    });
+    server.registerTool('delete_signature', {
+        title: 'Delete Signature',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        description: 'Permanently delete a project-scoped sending signature block.',
+        inputSchema: { id: z.string().uuid() },
+    }, async ({ id }) => {
+        const projectId = getProjectId();
+        const { data: existing, error: existingError } = await db()
+            .from('signature_blocks')
+            .select('id, name, site_id')
+            .eq('id', id)
+            .eq('project_id', projectId)
+            .maybeSingle();
+        if (existingError)
+            return j({ error: existingError.message });
+        if (!existing)
+            return j({ error: 'Signature not found', code: 'NOT_FOUND' });
+        const { error } = await db()
+            .from('signature_blocks')
+            .delete()
+            .eq('id', id)
+            .eq('project_id', projectId);
+        if (error)
+            return j({ error: error.message });
+        await logAudit({
+            action: 'signature.deleted',
+            resourceType: 'signature',
+            resourceId: id,
+            details: { name: existing.name, site_id: existing.site_id, via: 'mcp' },
+        });
+        return j({ ok: true, deleted: id });
+    });
+}

package/build/tools/sites.js

@@ -73,9 +73,10 @@ const createSenderSchema = {
     sending_domain: z.string().min(1).optional().describe('Legacy domain text'),
     from_email: z.string().email().optional().describe('Legacy full from address'),
     from_name: z.string().min(1),
+    physical_address: z.string().min(1).describe('CAN-SPAM-required physical mailing address for this sender. Must be an explicit value - there is no default.'),
     reply_to: z.string().email().optional(),
 };
-async function createSender({ name, slug, domain_id, local_part, sending_domain, from_email, from_name, reply_to, }) {
+async function createSender({ name, slug, domain_id, local_part, sending_domain, from_email, from_name, physical_address, reply_to, }) {
     const limit = await checkPlanLimit('sites');
     if (!limit.allowed)
         return txt(`Site limit reached (${limit.current}/${limit.limit}).`);
@@ -93,6 +94,7 @@ async function createSender({ name, slug, domain_id, local_part, sending_domain,
         is_shared_domain: domain.is_shared_domain,
         from_email: domain.from_email,
         from_name,
+        physical_address,
         reply_to: reply_to ?? null,
     })
         .select()

package/build/tools/skills.d.ts

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

package/build/tools/skills.js

@@ -0,0 +1,29 @@
+import { OPERATOR_SKILLS, getOperatorSkill } from '@sendinel/domain';
+import { z } from 'zod';
+const txt = (text) => ({ content: [{ type: 'text', text }] });
+const j = (data) => txt(JSON.stringify(data, null, 2));
+export function registerSkillTools(server) {
+    server.registerTool('list_operator_skills', {
+        title: 'List Operator Skills',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'List the Sendinel operator skills catalog: named, guided workflows that sequence existing MCP tools in a known-good order. Use this to discover which workflow fits a task before calling individual tools directly; use get_operator_skill for the full steps.',
+        inputSchema: {},
+    }, async () => {
+        return j({
+            skills: OPERATOR_SKILLS.map(({ name, description, metadata }) => ({ name, description, metadata })),
+        });
+    });
+    server.registerTool('get_operator_skill', {
+        title: 'Get Operator Skill',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Get one Sendinel operator skill by name, including its full workflow body: the guided steps and which MCP tools to call, in order, to complete it.',
+        inputSchema: {
+            name: z.string().min(1).describe('Skill name from list_operator_skills, e.g. "sendinel-campaign-build-launch".'),
+        },
+    }, async ({ name }) => {
+        const skill = getOperatorSkill(name);
+        if (!skill)
+            return txt(`Unknown skill: ${name}. Call list_operator_skills to see available skills.`);
+        return j(skill);
+    });
+}