@sendinel/mcp-server 1.0.183 → 1.0.184

package/build/lib/how-to-recipes.js

@@ -1,4 +1,5 @@
 /** Hand-written workflows, checked against the registered schemas in CI (#4061). */
+import { SEGMENT_OPERATORS_DESCRIPTION } from '@sendinel/domain';
 import { rankTools, scoreTool, tokenize, TOOL_ALIASES } from '../tools/tool-search.js';
 const approval = { required: true, how: 'returns approve_url; re-call with approval_id' };
 const from = (n, field) => `<from step ${n}: ${field}>`;
@@ -103,21 +104,48 @@ export const HOW_TO_RECIPES = [
         gotchas: [projectRule, 'No recorded bounce is not proof that an email arrived. Do not remove suppressions as a diagnostic step. Broader diagnose_delivery_issue requires write scope despite its read-only annotation.'],
         done_when: 'Explain the recorded bounce evidence and next action, or explicitly state that no matching bounce was recorded.',
     },
+    {
+        id: 'build-a-segment', title: 'Build a segment',
+        when_to_use: 'Create a saved audience segment with explicit rules and preview its membership.',
+        synonyms: ['build a segment', 'create segment', 'segment rules', 'audience filters'],
+        requires: { scopes: ['write'], tester_ok: false },
+        steps: [
+            { n: 1, tool: 'create_segment', args_example: { name: 'Engaged customers', rules: { op: 'AND', conditions: [{ field: 'lifecycle_stage', operator: 'eq', value: 'customer' }, { field: 'engagement_score', operator: 'gte', value: 50 }] } }, note: `Worked example: customers with engagement_score >= 50. ${SEGMENT_OPERATORS_DESCRIPTION}` },
+            { n: 2, tool: 'preview_segment', args_example: { segment_id: from(1, 'id') }, note: 'Review total_contacts and the sample; create_segment also returns estimated_contacts. Counts are dynamic and are not proof of send eligibility.' },
+        ],
+        gotchas: [projectRule, 'Use match_all:true explicitly for everyone. Empty or malformed rules are rejected. Preview does not send or enroll anyone.'],
+        done_when: 'The saved rules and preview match the intended audience.',
+    },
+    {
+        id: 'draft-a-template', title: 'Draft a template',
+        when_to_use: 'Save supplied email content as a reusable template, preview it and copy it into a campaign step.',
+        synonyms: ['draft a template', 'create template', 'template to campaign', 'use a template in a campaign'],
+        requires: { scopes: ['write'], tester_ok: false },
+        steps: [sender,
+            { n: 2, tool: 'create_template', args_example: { name: 'Product update', brief: 'Reusable product update', subject_hint: 'Your product update', body_html: '<p>Here is your product update.</p>' }, note: 'brief is required even with HTML; it is stored as a description/label without AI generation or AI credits. For AI-generated content use create_template_from_brief instead.' },
+            { n: 3, tool: 'get_template', args_example: { id: from(2, 'template.id') }, note: 'Read the saved subject_hint and body_html.' },
+            { n: 4, tool: 'preview_email', args_example: { site_id: from(1, '0.id'), subject: from(3, 'template.subject_hint'), body_html: from(3, 'template.body_html') }, note: 'Review the rendered content with sample contact data; this sends nothing.' },
+            { n: 5, tool: 'list_templates', args_example: { search: 'Product update' }, note: 'Verify the reusable template is discoverable; paginate if truncated.' },
+            { n: 6, tool: 'create_campaign', args_example: { site_id: from(1, '0.id'), name: 'Product update sequence', type: 'sequence' }, note: 'Optional use in a campaign: creates a new draft; use an existing draft instead if appropriate.' },
+            { n: 7, tool: 'add_campaign_step', args_example: { campaign_id: from(6, 'id'), step_order: 0, subject: from(3, 'template.subject_hint'), body_html: from(3, 'template.body_html') }, note: 'Copy content from get_template. No template_id parameter exists here; template_id/template_vars in the response are reserved for this path. This draft is not activated.' },
+        ],
+        gotchas: [projectRule, previewRule, 'Later template edits do not update copied step content. Sequences need a separate enrollment/activation plan and approval. For a one-off segment broadcast use send_broadcast with copied html and subject, segment_id and optional send_at; approval is required.'],
+        done_when: 'The template is saved, previewed and listed; if requested, its content is copied into an unactivated campaign step.',
+    },
     {
         id: 'campaign-build-launch', title: 'Build and launch an email campaign',
-        when_to_use: 'Manually assemble and review a campaign before activating its saved content.',
-        synonyms: ['build campaign', 'draft campaign', 'campaign build launch', 'campaign from brief'],
+        when_to_use: 'Review and schedule a one-off email campaign for a saved segment.',
+        synonyms: ['build campaign', 'draft campaign', 'campaign build launch', 'campaign from brief', 'schedule a campaign for a segment'],
         requires: { scopes: ['write'], tester_ok: false },
         steps: [sender,
-            { n: 2, tool: 'create_campaign', args_example: { site_id: from(1, '0.id'), name: 'Reviewed campaign', type: 'broadcast' } },
-            { n: 3, tool: 'add_campaign_step', args_example: { campaign_id: from(2, 'id'), step_order: 0, subject: 'Your update', body_html: '<p>Your reviewed update.</p>' } },
-            { n: 4, tool: 'send_test_email', args_example: { to_email: 'person@example.com', site_id: from(1, '0.id'), step_id: from(3, 'id'), dry_run: true }, note: 'Use an authorized preview address. Keep dry_run:true: render only, without approval.' },
-            { n: 5, tool: 'preview_campaign_audience', args_example: { campaign_id: from(2, 'id') }, note: 'This tool shows active enrollments only, not the future audience of a draft. Review the sender and segment separately; the activation approval describes trigger behavior.' },
-            { n: 6, tool: 'activate_campaigns', args_example: { campaign_ids: [from(2, 'id')] }, approval, note: 'Show content, audience and approve_url; wait for approval.' },
-            { n: 7, tool: 'activate_campaigns', args_example: { approval_id: from(6, 'approval_id') }, approval, note: 'ONLY approval_id after human approval.' },
+            { n: 2, tool: 'list_segments', args_example: {}, note: 'Choose the intended saved segment.' },
+            { n: 3, tool: 'preview_segment', args_example: { segment_id: from(2, '0.id') }, note: 'Review membership; actual eligible recipients are resolved by send_broadcast.' },
+            { n: 4, tool: 'preview_email', args_example: { site_id: from(1, '0.id'), subject: 'Your update', body_html: '<p>Your reviewed update.</p>' }, note: 'Review the real renderer without sending.' },
+            { n: 5, tool: 'send_broadcast', args_example: { site_id: from(1, '0.id'), segment_id: from(2, '0.id'), subject: 'Your update', html: '<p>Your reviewed update.</p>' }, approval, note: 'To schedule, add send_at with the requested future ISO instant. Show the finished content, eligible recipient count, sender, schedule and approve_url; wait for human approval. This call sends nothing.' },
+            { n: 6, tool: 'send_broadcast', args_example: { approval_id: from(5, 'approval_id') }, approval, note: 'After approval pass ONLY approval_id. Creates, enrolls and activates the approved broadcast.' },
         ],
-        gotchas: [projectRule, previewRule, 'launch_campaign takes briefs and builds a new campaign; it does not launch a campaign_id. Draft approval and action approval are separate.'],
-        done_when: 'The saved, reviewed campaign is activated successfully for its intended audience.',
+        gotchas: [projectRule, previewRule, 'For saved sequences/journeys use create_campaign, add_campaign_step and activate_campaigns with human approval; activation alone enrolls nobody. broadcast_to_segment is the immediate segment broadcast alternative. launch_campaign builds a NEW campaign from briefs.'],
+        done_when: 'Approved execution reports the intended broadcast queued or scheduled; actual delivery requires separate verification.',
     },
     {
         id: 'list-hygiene', title: 'Audit list hygiene and duplicates',

package/build/tools/campaign-sets.js

@@ -281,7 +281,7 @@ export function registerCampaignSetTools(server) {
     server.registerTool('activate_campaigns', {
         title: 'Activate Campaigns',
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
-        description: 'Turn on a set of draft or paused campaigns behind one human approval. Call 1: give campaign_set_id or campaign_ids; it returns one approval_id with a summary of every campaign, and activates nothing. After a person approves (approve_url works on a phone), call again with only approval_id. It refuses if any campaign or email changed after approval. Activating a broadcast enrolls nobody; use send_broadcast or broadcast_to_segment to create, enroll and activate a broadcast for sending.',
+        description: 'Turn on a set of draft or paused campaigns behind one human approval. Call 1: give campaign_set_id or campaign_ids; it returns one approval_id with a summary of every campaign, and activates nothing. After a person approves (approve_url works on a phone), call again with only approval_id. It refuses if any campaign or email changed after approval. Use this for saved sequences/journeys. To schedule a one-off segment broadcast use send_broadcast with segment_id and send_at; its content and audience require approval. Activating a broadcast enrolls nobody; use send_broadcast or broadcast_to_segment to create, enroll and activate a broadcast for sending.',
         inputSchema: {
             campaign_set_id: z.string().uuid().optional(),
             campaign_ids: z.array(z.string().uuid()).min(1).max(50).optional(),

package/build/tools/campaigns.js

@@ -886,7 +886,7 @@ export function registerCampaignTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Create a new email campaign. For triggered campaigns, provide one trigger shape: trigger_event_name, trigger_tag, trigger_type=date_field with trigger_config, or segment_id for ongoing audience targeting. For type=broadcast, send_at schedules the send for a future instant; the campaign must still be activated via update_campaign_status.',
+        description: 'Create a new email campaign. For triggered campaigns, provide one trigger shape: trigger_event_name, trigger_tag, trigger_type=date_field with trigger_config, or segment_id for ongoing audience targeting. For type=broadcast, send_at schedules the send for a future instant; the draft still needs activation via activate_campaigns (human approval), which enrolls nobody. Use create_campaign plus steps and activate_campaigns for saved sequences/journeys; for a one-off segment broadcast use send_broadcast with segment_id and optional send_at, which creates, enrolls and activates after approval.',
         inputSchema: {
             ...reentryFields,
             site_id: z.string().uuid(),
@@ -900,7 +900,7 @@ export function registerCampaignTools(server) {
             trigger_type: z.enum(['date_field']).optional().describe('Set for elapsed-time triggers keyed on a contact custom_properties date field'),
             trigger_config: z.record(z.string(), z.unknown()).nullable().optional().describe('For trigger_type=date_field: { field, days_before?, recurring? }. Otherwise: { events?: string[], tags?: string[] }.'),
             segment_id: z.string().uuid().nullable().optional().describe('Segment UUID for ongoing audience targeting; membership is re-evaluated on sends'),
-            send_at: z.string().datetime().nullable().optional().describe('For type=broadcast only: ISO 8601 instant to schedule the send. Must be in the future. Set null for no schedule. The campaign must still be activated via update_campaign_status.'),
+            send_at: z.string().datetime().nullable().optional().describe('For type=broadcast only: ISO 8601 instant to schedule the send. Must be in the future. Set null for no schedule. Activation via activate_campaigns requires human approval and enrolls nobody. To schedule a one-off segment broadcast use send_broadcast with segment_id and send_at.'),
             send_class: z.enum(['broadcast', 'product']).optional().describe("Who may receive it when the project's consent gate is on: 'broadcast' (default) = only contacts who opted in to marketing; 'product' = also the customer's signed-up users (onboarding, trial, account mail)."),
         },
     }, async ({ site_id, name, type, description, sends_per_hour, requires_approval, trigger_event_name, trigger_tag, trigger_type, trigger_config, segment_id, send_at, send_class, reentry_mode, period_key }) => {
@@ -952,7 +952,7 @@ export function registerCampaignTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Add an email step to a campaign. Requires a non-blank subject and body_html, body_text, or blocks that render to content. For A/B testing, add multiple steps with the same step_order but different variant_label values.',
+        description: 'Add an email step to a campaign. Requires a non-blank subject and body_html, body_text, or blocks that render to content. To use a stored template, call get_template and copy subject_hint into subject and body_html into body_html (and body_text if available). This tool accepts no template_id or template_vars; those response fields are reserved here and are not set by this tool. For A/B testing, add multiple steps with the same step_order but different variant_label values.',
         inputSchema: z.object({
             campaign_id: z.string().uuid(),
             step_order: z.number().int().min(0).describe('Position in sequence (0 = first)'),
@@ -1326,7 +1326,7 @@ export function registerCampaignTools(server) {
             idempotentHint: false,
             openWorldHint: true,
         },
-        description: 'Create a one-email broadcast campaign for an existing segment, enroll eligible contacts immediately, and activate it. Uses two-call confirmation plus approval before sending to real contacts.',
+        description: 'Create a one-email broadcast campaign for an existing segment, enroll eligible contacts immediately, and activate it. Uses two-call confirmation plus approval before sending to real contacts. Use this for an immediate one-off segment broadcast; for a scheduled segment broadcast use send_broadcast with segment_id and send_at. For sequences/journeys use create_campaign, add_campaign_step and activate_campaigns.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site/sender to send from'),
             segment_id: z.string().uuid().describe('Existing segment to target'),
@@ -1488,7 +1488,7 @@ export function registerCampaignTools(server) {
             idempotentHint: false,
             openWorldHint: true,
         },
-        description: 'Send a one-off email in two calls. Call 1: give an audience (audience in plain words, or segment_id) and content (brief for an AI draft, or html + subject); it returns the finished email, the recipient count, the sender and an approval_id, and sends nothing. A person approves it (approve_url works on a phone). Call 2: pass ONLY approval_id; it sends exactly what was approved. Use this for "send an email to…", newsletters, announcements.',
+        description: 'Send a one-off email in two calls. Call 1: give an audience (audience in plain words, or segment_id) and content (brief for an AI draft, or html + subject); it returns the finished email, the recipient count, the sender and an approval_id, and sends nothing. A person approves it (approve_url works on a phone). Call 2: pass ONLY approval_id; it sends exactly what was approved. Use this for one-off segment broadcasts: segment_id plus optional send_at schedules the campaign after approval of the exact content and audience. For sequences/journeys use create_campaign, add_campaign_step and activate_campaigns.',
         inputSchema: {
             audience: z.string().min(3).max(500).optional().describe('Who gets it, in plain words (for example "trial users who have not opened anything"). Use this or segment_id.'),
             segment_id: z.string().uuid().optional().describe('A saved segment. Use this or audience.'),

package/build/tools/how-to.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { requestContext } from '../db.js';
+import { LIMITED_GRANT_DENIED_TOOLS } from '../lib/limited-grant.js';
 import { HOW_TO_RECIPES, matchRecipes } from '../lib/how-to-recipes.js';
 import { logHowToCall } from '../lib/how-to-usage.js';
 import { getRegisteredToolGroups, isTesterConnection } from '../server.js';
@@ -14,7 +16,11 @@ export function registerHowTo(server, options = {}) {
         },
     }, async ({ goal, limit }) => {
         const scopes = options.scopes?.filter((s) => s !== 'gateway');
-        const groups = getRegisteredToolGroups({ ...options, scopes });
+        const registered = getRegisteredToolGroups({ ...options, scopes });
+        const limited = requestContext()?.allowedProjectIds != null;
+        const groups = limited
+            ? Object.fromEntries(Object.entries(registered).filter(([name]) => !LIMITED_GRANT_DENIED_TOOLS.has(name)))
+            : registered;
         const available = HOW_TO_RECIPES.filter((recipe) => (!isTesterConnection(scopes) || recipe.requires.tester_ok)
             && recipe.steps.every((step) => Object.hasOwn(groups, step.tool)));
         const tools = Object.entries(groups).map(([name, group]) => ({ name, group, description: '' }));

package/build/tools/segments.js

@@ -7,7 +7,7 @@ import { getProjectId } from '../project.js';
 import { dbErrorResult, dbToolError, toolError } from '../lib/db-error.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { AI_MAX_TOKENS, outputConfig, anthropicCheckedText } from '@sendinel/domain';
-import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, hydrateEmailSendsContacts, isSegmentRulesError, normalizeSegmentRulesToTree, prepareSegmentRulesForStorage, readAllRows, } from '@sendinel/domain';
+import { SEGMENT_OPERATORS_DESCRIPTION, applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, hydrateEmailSendsContacts, isSegmentRulesError, normalizeSegmentRulesToTree, prepareSegmentRulesForStorage, readAllRows, } from '@sendinel/domain';
 async function loadFieldTypes(projectId) {
     const client = db();
     const scoped = typeof client.schema === 'function' ? client.schema('email') : client;
@@ -77,7 +77,7 @@ export function registerSegmentTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Create a saved segment with filter rules. Segments evaluate dynamically at send time.',
+        description: `Create a saved segment with filter rules. Segments evaluate dynamically at send time. ${SEGMENT_OPERATORS_DESCRIPTION}`,
         inputSchema: {
             name: z.string().min(1).describe('Segment name (unique per project)'),
             description: z.string().optional(),
@@ -160,7 +160,7 @@ export function registerSegmentTools(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Update a segment name, description, or rules',
+        description: `Update a segment name, description, or rules. ${SEGMENT_OPERATORS_DESCRIPTION}`,
         inputSchema: {
             segment_id: z.string().uuid(),
             name: z.string().optional(),

package/build/tools/templates.js

@@ -241,10 +241,10 @@ export function registerTemplateTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Create a new email template. Use create_template_from_brief to AI-generate the content.',
+        description: 'Save an email template from supplied content. brief is a required description/label stored as brief_template, even with body_html; this tool performs no AI generation and consumes no AI credits. Use create_template_from_brief to AI-generate content using the site brand voice.',
         inputSchema: {
             name: templateName,
-            brief: z.string().min(1),
+            brief: z.string().min(1).describe('Required description/label; stored only, no AI generation or AI credits.'),
             subject_hint: z.string().optional(),
             body_html: z.string().optional(),
             category: z.string().optional(),

package/package.json

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