@sendinel/mcp-server 1.0.13 → 1.0.14

package/README.md

@@ -12,7 +12,7 @@ AI-controlled email operations control plane for campaigns, contacts, segments,
 
 ## Tool groups
 
-Sendinel currently exposes 34 tool groups and 302 tools (gateway mode adds 3 meta-tools). These counts are checked against the tool registry in CI, so this table matches what ships.
+Sendinel currently exposes 34 tool groups and 308 tools (gateway mode adds 3 meta-tools). These counts are checked against the tool registry in CI, so this table matches what ships.
 
 | Group | Count | Purpose |
 |-------|-------|---------|
@@ -23,7 +23,7 @@ Sendinel currently exposes 34 tool groups and 302 tools (gateway mode adds 3 met
 | `approvals` | 2 | Poll and list risk-tiered action approvals |
 | `automations` | 7 | Automation triggers, previews, and response-gated escalation ladders |
 | `brand_kit` | 5 | Brand Core text import, media library upload/URL ingest, asset-context reads |
-| `campaigns` | 30 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates |
+| `campaigns` | 36 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates |
 | `cloud-import` | 6 | Cloud storage import |
 | `compound` | 4 | Higher-level campaign/template/site setup and delivery diagnosis workflows |
 | `connector` | 6 | BYOD connector status, table discovery, schema/view setup, mapping, resync |

package/build/server.js

@@ -78,6 +78,9 @@ const WRITE_TOOLS = new Set([
     'create_subscriber_view', 'update_subscriber_view', 'delete_subscriber_view',
     'enrich_subscriber',
     'create_campaign', 'update_campaign', 'delete_campaign', 'add_campaign_step', 'update_campaign_status',
+    // #3348 - branch/goal writes. Same scope as the campaign edits they sit alongside:
+    // they change what the send engine does to enrolled contacts, so they are not read-only.
+    'add_campaign_branch', 'remove_campaign_branch', 'set_campaign_goal', 'remove_campaign_goal',
     'review_campaign_portfolio',
     'list_campaign_steps', 'update_campaign_step', 'delete_campaign_step',
     'enroll_contact', 'enroll_segment', 'broadcast_to_segment', 'get_enrollment_status', 'clone_campaign', 'clone_sequence_template', 'generate_email',

package/build/tools/campaigns.js

@@ -235,6 +235,47 @@ function normalizeConsistencyResult(value) {
         flags,
     };
 }
+// #3348 - kept in step with the dashboard routes these tools mirror:
+//   app/api/dashboard/campaigns/[id]/steps/[stepId]/branches/route.ts
+//   app/api/dashboard/campaigns/goals/route.ts
+// If those lists change, change these. A value MCP accepts that REST rejects (or the
+// reverse) is a divergence between two front doors onto the same engine.
+const CAMPAIGN_BRANCH_CONDITIONS = ['tag_added', 'lifecycle_reached', 'conversion', 'link_clicked', 'custom_event', 'reply', 'click', 'booking'];
+const CAMPAIGN_BRANCH_ACTIONS = ['goto_step', 'goto_campaign', 'exit', 'complete'];
+const CAMPAIGN_GOAL_TYPES = ['conversion', 'tag_added', 'lifecycle_reached', 'link_clicked', 'custom_event'];
+const CAMPAIGN_GOAL_ACTIONS = ['exit', 'complete', 'move_to_campaign'];
+/** Tenant guard: every branch/goal tool confirms the campaign belongs to the caller's project first. */
+async function campaignInProject(campaignId) {
+    const { data } = await db()
+        .from('campaigns')
+        .select('id')
+        .eq('id', campaignId)
+        .eq('project_id', getProjectId())
+        .maybeSingle();
+    return Boolean(data);
+}
+/** Mirrors validateTarget() in the branches REST route. */
+async function validateBranchTarget(campaignId, action, targetStepId, targetCampaignId) {
+    if (action === 'goto_step') {
+        if (!targetStepId)
+            return 'target_step_id is required for goto_step';
+        const { data } = await db()
+            .from('campaign_steps')
+            .select('id')
+            .eq('id', targetStepId)
+            .eq('campaign_id', campaignId)
+            .maybeSingle();
+        if (!data)
+            return 'target_step_id must be a step in the same campaign';
+    }
+    if (action === 'goto_campaign') {
+        if (!targetCampaignId)
+            return 'target_campaign_id is required for goto_campaign';
+        if (!(await campaignInProject(targetCampaignId)))
+            return 'target_campaign_id must be a campaign in this project';
+    }
+    return null;
+}
 export function registerCampaignTools(server) {
     server.registerTool('review_campaign_portfolio', {
         title: 'Review Campaign Portfolio',
@@ -2528,4 +2569,164 @@ Return ONLY valid JSON with this exact shape:
             return j({ error: error.message });
         return j({ success: true });
     });
+    // #3348 - campaign branching and goals were fully built (schema, engine, dashboard API)
+    // but unreachable from MCP, so an agent could compose the emails in a campaign and not
+    // the logic that makes it a campaign rather than a list of templates. The send engine
+    // (cron/enqueue-sends) already reads both tables; these tools only let callers write
+    // what it already honours. Validation mirrors the dashboard routes exactly -- a value
+    // accepted here that the REST route would reject is a divergence, not a convenience.
+    server.registerTool('list_campaign_branches', {
+        title: 'List Campaign Branches',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'List the conditional branches, if/then rules and logic already set on a campaign, optionally filtered to one step. Shows each condition, what happens when it matches, and the priority order they are evaluated in. Use this to see the existing branching before adding or changing a rule.',
+        inputSchema: {
+            campaign_id: z.string().uuid(),
+            step_id: z.string().uuid().optional().describe('Only branches leaving this step'),
+        },
+    }, async ({ campaign_id, step_id }) => {
+        if (!(await campaignInProject(campaign_id)))
+            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+        let query = db()
+            .from('campaign_step_branches')
+            .select('id, from_step_id, condition_type, condition_value, action, target_step_id, target_campaign_id, priority, created_at')
+            .eq('campaign_id', campaign_id)
+            .order('priority', { ascending: true });
+        if (step_id)
+            query = query.eq('from_step_id', step_id);
+        const { data, error } = await query;
+        if (error)
+            return j({ error: error.message });
+        return j({ campaign_id, branches: data ?? [], count: (data ?? []).length });
+    });
+    server.registerTool('add_campaign_branch', {
+        title: 'Add Campaign Branch',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: 'Add an if/then rule to a campaign step so the sequence branches on what the contact does. Use this for conditional logic like: if they clicked the link send a different follow-up, if they replied skip ahead, if a tag was added move them to another campaign, otherwise continue. When the condition matches, the branch action runs instead of continuing to the next step. Lower priority is evaluated first.',
+        inputSchema: {
+            campaign_id: z.string().uuid(),
+            from_step_id: z.string().uuid().describe('The step this branch leaves from'),
+            condition_type: z.enum(CAMPAIGN_BRANCH_CONDITIONS).describe('What triggers the branch'),
+            condition_value: z.string().optional().describe('Condition argument, e.g. the tag name for tag_added or the URL for link_clicked'),
+            action: z.enum(CAMPAIGN_BRANCH_ACTIONS).describe('goto_step and goto_campaign require their matching target'),
+            target_step_id: z.string().uuid().optional().describe('Required when action is goto_step'),
+            target_campaign_id: z.string().uuid().optional().describe('Required when action is goto_campaign'),
+            priority: z.number().int().min(0).optional().default(0).describe('Lower runs first (default 0)'),
+        },
+    }, async ({ campaign_id, from_step_id, condition_type, condition_value, action, target_step_id, target_campaign_id, priority }) => {
+        if (!(await campaignInProject(campaign_id)))
+            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+        // Same requirement the REST route enforces: an action naming a target must have one,
+        // and that target must belong to this project.
+        const targetError = await validateBranchTarget(campaign_id, action, target_step_id ?? null, target_campaign_id ?? null);
+        if (targetError)
+            return j({ error: targetError, code: 'INVALID_TARGET' });
+        const { data, error } = await db()
+            .from('campaign_step_branches')
+            .insert({
+            campaign_id,
+            from_step_id,
+            condition_type,
+            condition_value: condition_value?.trim() || null,
+            action,
+            target_step_id: action === 'goto_step' ? target_step_id : null,
+            target_campaign_id: action === 'goto_campaign' ? target_campaign_id : null,
+            priority: priority ?? 0,
+        })
+            .select('id, from_step_id, condition_type, condition_value, action, target_step_id, target_campaign_id, priority')
+            .single();
+        if (error)
+            return j({ error: error.message });
+        await logAudit({ action: 'add_campaign_branch', resourceType: 'campaign', resourceId: campaign_id, details: { branch_id: data?.id, condition_type, branch_action: action } }).catch(() => { });
+        return j({ success: true, branch: data });
+    });
+    server.registerTool('remove_campaign_branch', {
+        title: 'Remove Campaign Branch',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        description: 'Delete or turn off a conditional branch rule on a campaign step, so that if/then path no longer applies. Contacts already routed by it are unaffected; only future evaluations change.',
+        inputSchema: { campaign_id: z.string().uuid(), branch_id: z.string().uuid() },
+    }, async ({ campaign_id, branch_id }) => {
+        if (!(await campaignInProject(campaign_id)))
+            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+        const { error } = await db()
+            .from('campaign_step_branches')
+            .delete()
+            .eq('id', branch_id)
+            .eq('campaign_id', campaign_id);
+        if (error)
+            return j({ error: error.message });
+        await logAudit({ action: 'remove_campaign_branch', resourceType: 'campaign', resourceId: campaign_id, details: { branch_id } }).catch(() => { });
+        return j({ success: true, removed: branch_id });
+    });
+    server.registerTool('list_campaign_goals', {
+        title: 'List Campaign Goals',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'List the goals, exit conditions and stop rules set on a campaign. A goal is what the campaign is asking the contact to do: once they do it, sending stops for them and the remaining reminders are skipped. Use this to check whether a campaign will stop nagging people who already converted or finished onboarding.',
+        inputSchema: { campaign_id: z.string().uuid() },
+    }, async ({ campaign_id }) => {
+        if (!(await campaignInProject(campaign_id)))
+            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+        const { data, error } = await db()
+            .from('campaign_goals')
+            .select('id, goal_type, goal_value, action, target_campaign_id, created_at')
+            .eq('campaign_id', campaign_id)
+            .order('created_at', { ascending: true });
+        if (error)
+            return j({ error: error.message });
+        return j({ campaign_id, goals: data ?? [], count: (data ?? []).length });
+    });
+    server.registerTool('set_campaign_goal', {
+        title: 'Set Campaign Goal',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: 'Set the goal or exit condition for a campaign so it will stop sending to a contact once they have done the thing it was asking for. Use this to stop reminders when someone finishes onboarding, completes signup, converts, has already converted, books, or gets tagged as done. Without a goal, every enrolled contact keeps receiving every remaining step and reminder even after they already completed the action, which is the usual cause of people being nagged after converting.',
+        inputSchema: {
+            campaign_id: z.string().uuid(),
+            goal_type: z.enum(CAMPAIGN_GOAL_TYPES),
+            goal_value: z.string().min(1).describe('What counts as met, e.g. the tag name, event name, or URL'),
+            action: z.enum(CAMPAIGN_GOAL_ACTIONS).optional().default('exit').describe('What to do once met (default: exit)'),
+            target_campaign_id: z.string().uuid().optional().describe('Required when action is move_to_campaign'),
+        },
+    }, async ({ campaign_id, goal_type, goal_value, action, target_campaign_id }) => {
+        if (!(await campaignInProject(campaign_id)))
+            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+        const resolvedAction = action ?? 'exit';
+        if (resolvedAction === 'move_to_campaign') {
+            if (!target_campaign_id)
+                return j({ error: 'target_campaign_id is required for move_to_campaign', code: 'INVALID_TARGET' });
+            if (!(await campaignInProject(target_campaign_id)))
+                return j({ error: 'target_campaign_id not found in this project', code: 'INVALID_TARGET' });
+        }
+        const { data, error } = await db()
+            .from('campaign_goals')
+            .insert({
+            campaign_id,
+            goal_type,
+            goal_value: goal_value.trim(),
+            action: resolvedAction,
+            target_campaign_id: resolvedAction === 'move_to_campaign' ? target_campaign_id : null,
+        })
+            .select('id, goal_type, goal_value, action, target_campaign_id')
+            .single();
+        if (error)
+            return j({ error: error.message });
+        await logAudit({ action: 'set_campaign_goal', resourceType: 'campaign', resourceId: campaign_id, details: { goal_id: data?.id, goal_type, goal_action: resolvedAction } }).catch(() => { });
+        return j({ success: true, goal: data });
+    });
+    server.registerTool('remove_campaign_goal', {
+        title: 'Remove Campaign Goal',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        description: 'Delete a goal or exit condition from a campaign so it no longer stops early for that reason. Warning: removing the last goal means enrolled contacts will keep receiving every remaining step and reminder even after they convert or finish onboarding.',
+        inputSchema: { campaign_id: z.string().uuid(), goal_id: z.string().uuid() },
+    }, async ({ campaign_id, goal_id }) => {
+        if (!(await campaignInProject(campaign_id)))
+            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+        const { error } = await db()
+            .from('campaign_goals')
+            .delete()
+            .eq('id', goal_id)
+            .eq('campaign_id', campaign_id);
+        if (error)
+            return j({ error: error.message });
+        await logAudit({ action: 'remove_campaign_goal', resourceType: 'campaign', resourceId: campaign_id, details: { goal_id } }).catch(() => { });
+        return j({ success: true, removed: goal_id });
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "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",