@sendinel/mcp-server 1.0.144 → 1.0.145

package/build/tools/campaigns.js

@@ -92,7 +92,11 @@ export function buildCampaignFiresOn(campaign) {
         parts.push(`event${events.length > 1 ? 's' : ''} ${events.map((e) => `"${e}"`).join(', ')} sent to /v1/events`);
     if (tags.length)
         parts.push(`tag${tags.length > 1 ? 's' : ''} ${tags.map((t) => `"${t}"`).join(', ')} added`);
-    if (campaign.segment_id)
+    if (campaign.type === 'broadcast') {
+        parts.length = 0;
+        parts.push(campaign.send_at ? `the scheduled send time (${campaign.send_at})` : 'nothing scheduled (no send_at set)');
+    }
+    else if (campaign.segment_id)
         parts.push('contacts entering its segment');
     let summary = parts.length ? `Fires on: ${parts.join('; ')}.` : 'Fires on: nothing (no trigger set).';
     const warnings = [];
@@ -731,7 +735,7 @@ export function registerCampaignTools(server) {
     }, async ({ site_id, status, limit, period }) => {
         let q = db()
             .from('campaigns')
-            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config, send_class, unsub_footer_template, requires_approval, approved_by, approved_at')
+            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config, send_class, unsub_footer_template, requires_approval, approved_by, approved_at, send_at')
             .eq('project_id', getProjectId())
             .order('created_at', { ascending: false })
             .limit(limit ?? 25);
@@ -2956,14 +2960,16 @@ Do not include body_html in your response; Sendinel renders body_html from block
     }, async ({ html, site_id, custom_variables, subject, body_text, trigger_event_name, event_keys }) => {
         const projectId = getProjectId();
         let voiceConfig = null;
+        let autoUnsubscribeFooter = true;
         if (site_id) {
             const { data: site } = await db()
                 .from('sites')
-                .select('brand_voice')
+                .select('brand_voice, unsub_link_enabled')
                 .eq('id', site_id)
                 .eq('project_id', projectId)
                 .maybeSingle();
             voiceConfig = site?.brand_voice ?? null;
+            autoUnsubscribeFooter = site?.unsub_link_enabled !== false;
         }
         // The brand kit's sign-off name applies to every site in the project (#3854).
         const { data: projectRow } = await db().from('projects').select('brand_settings').eq('id', projectId).maybeSingle();
@@ -2973,16 +2979,19 @@ Do not include body_html in your response; Sendinel renders body_html from block
             .filter((row) => !site_id || row.id === site_id)
             .flatMap((row) => [sendingHostOf(row.sending_domain), sendingHostOf(row.from_email)])
             .filter((host) => Boolean(host));
+        const contacts = await contactPropertyKeys(projectId);
+        const { data: definitions } = await db().from('custom_field_definitions').select('key').eq('project_id', projectId);
+        const contactVariables = [...(contacts?.keys ?? []), ...(definitions ?? []).map((field) => field.key)].map((key) => `custom.${key}`);
         let sourcedKeys;
         if (trigger_event_name || event_keys) {
             const fromHistory = trigger_event_name ? await eventKeysFromHistory(projectId, trigger_event_name) : [];
-            const contacts = await contactPropertyKeys(projectId);
             sourcedKeys = fromHistory === null || contacts === null
                 ? null
-                : [...(event_keys ?? []), ...fromHistory, ...contacts.keys.map((key) => `custom.${key}`)];
+                : [...(event_keys ?? []), ...fromHistory, ...contactVariables];
         }
         const result = validateTemplate(html, voiceConfig, {
-            customVariables: [...(custom_variables ?? []), ...(sourcedKeys ?? [])],
+            customVariables: [...(custom_variables ?? []), ...contactVariables, ...(sourcedKeys ?? [])],
+            autoUnsubscribeFooter,
             subject,
             bodyText: body_text,
             brandSettings: projectRow?.brand_settings ?? null,
@@ -3004,7 +3013,7 @@ Do not include body_html in your response; Sendinel renders body_html from block
             else if (!result.errors.some((error) => error.includes(issue.excerpt)))
                 result.warnings.push(issue.message);
         }
-        return j({ ...result, valid: result.errors.length === 0 });
+        return j({ ...result, valid: result.errors.length === 0, ...(result.errors.length ? { code: 'validation_failed' } : {}) });
     });
     server.registerTool('check_content_consistency', {
         title: 'Check Content Consistency',

package/build/tools/contacts.js

@@ -493,8 +493,8 @@ function primaryContactValue(value) {
 }
 // #3623: last_transactional_at / total_transactional_sent are service (transactional) mail, tracked apart
 // from the marketing last_emailed_at / total_emails_sent. NULL means none recorded, not "never".
-const SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage';
-const SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage';
+const SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage, tags';
+const SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage, tags';
 const SEGMENT_SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_opens, total_clicks';
 const SEGMENT_SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_opens, total_clicks';
 const UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), custom_properties, tags, phone_e164, timezone';
@@ -962,7 +962,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List contacts, optionally filtered by site, search term, and/or a saved subscriber view. Explicit arguments and saved-view filters are combined to narrow the result.',
+        description: 'List contacts including tags, optionally filtered by site, search term, and/or a saved subscriber view. Explicit arguments and saved-view filters are combined to narrow the result.',
         inputSchema: {
             site_id: z.string().uuid().optional(),
             company_id: z.string().uuid().optional(),

package/build/tools/gateway.js

@@ -7,9 +7,9 @@ import { getRegisteredToolGroups, registerAllTools } from '../server.js';
 import { rankTools, scoreTool, TOOL_ALIASES, tokenize } from './tool-search.js';
 const textResult = (text) => ({ content: [{ type: 'text', text }] });
 const jsonResult = (data) => textResult(JSON.stringify(data, null, 2));
-const notFound = (message) => ({
+const notFound = (message, code = 'not_found') => ({
     isError: true,
-    content: [{ type: 'text', text: message }],
+    ...jsonResult({ error: message, code }),
 });
 /**
  * Plain words people use for a tool (#3669, #4059). The map lives in tool-search.ts so how_to can
@@ -49,7 +49,7 @@ async function buildCatalog(options) {
 function unknownKeyMessage(keys) {
     const list = keys.map((k) => `'${k}'`).join(', ');
     const hinted = keys.some((k) => ARGS_LOOKALIKES.has(k.toLowerCase()));
-    return `Unknown key(s) on invoke_tool: ${list}${hinted ? "; did you mean 'args'?" : ''} Valid keys: name, args (alias: arguments).`;
+    return `Unknown key(s) on invoke_tool: ${list}${hinted ? "; did you mean 'args'?" : ''} Valid keys: name, args (alias: arguments), project_id.`;
 }
 const ARGS_LOOKALIKES = new Set(['args', 'argument', 'params', 'input', 'parameters']);
 function declaredProperties(inputSchema) {
@@ -83,20 +83,28 @@ export function registerGatewayTools(server, options) {
     const getCatalog = () => (catalogPromise ??= buildCatalog(options));
     server.registerTool('search_tools', {
         title: 'Search Tools',
-        description: 'Search the permitted Sendinel MCP tool catalog by keyword and/or group. Returns name, group, and description. Call describe_tool for the full input schema before invoke_tool.',
+        description: 'Search the permitted Sendinel MCP tool catalog by keyword and/or group. Returns name, group, and description. Optional limit/offset page ranked search results or explicit browsing. Call describe_tool for the full input schema before invoke_tool.',
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             query: z.string().optional().describe('Words to match against tool name, group, description, or common phrasing (for example "send email")'),
             group: z.string().optional().describe('Restrict results to one tool group, for example campaigns'),
+            limit: z.number().int().min(1).max(50).optional().describe('Page size (1–50); ranked search defaults to 10, browsing stays uncapped unless paging is supplied'),
+            offset: z.number().int().min(0).optional().describe('Zero-based result offset (default 0)'),
         },
-    }, async ({ query, group }) => {
+    }, async ({ query, group, limit, offset }) => {
         const catalog = await getCatalog();
         const q = query?.trim().toLowerCase() ?? '';
         const requestedGroup = group?.trim();
         const scoped = catalog.entries.filter((tool) => !requestedGroup || tool.group === requestedGroup);
         const summarize = ({ name, group, description }) => ({ name, group, description });
+        const start = offset ?? 0;
+        const pageSize = limit ?? SEARCH_LIMIT;
         if (!q) {
-            return jsonResult({ tools: scoped.map(summarize), total: scoped.length });
+            if (limit === undefined && offset === undefined)
+                return jsonResult({ tools: scoped.map(summarize), total: scoped.length });
+            const page = scoped.slice(start, start + pageSize);
+            const truncated = start + page.length < scoped.length;
+            return jsonResult({ tools: page.map(summarize), total: scoped.length, truncated, ...(truncated ? { next_offset: start + page.length } : {}) });
         }
         const { matches, nearest } = rankTools(scoped, q);
         if (matches.length === 0) {
@@ -108,12 +116,14 @@ export function registerGatewayTools(server, options) {
                 hint: 'No tool matched that phrasing. The nearest tools are listed; try a shorter keyword, or browse with the group filter.',
             });
         }
-        const top = matches.slice(0, SEARCH_LIMIT);
+        const top = matches.slice(start, start + pageSize);
+        const truncated = start + top.length < matches.length;
         return jsonResult({
             tools: top.map(({ entry }) => summarize(entry)),
             total: matches.length,
             ranked: true,
-            ...(matches.length > top.length ? { truncated: true } : {}),
+            truncated,
+            ...(truncated ? { next_offset: start + top.length } : {}),
         });
     });
     server.registerTool('describe_tool', {
@@ -139,15 +149,16 @@ export function registerGatewayTools(server, options) {
             name: z.string().min(1).describe('Tool name to invoke'),
             args: z.record(z.string(), z.unknown()).optional().describe('Arguments for the target tool'),
             arguments: z.record(z.string(), z.unknown()).optional().describe('Alias for args (the MCP-standard field name). Provide args or arguments, not both.'),
+            project_id: z.string().uuid().optional().describe('Per-call project override, same as on any tool. The hosted transport selects and strips it before invocation; direct stdio calls use the configured project.'),
         }),
     }, async (input) => {
-        const { name, args, arguments: argumentsAlias, ...rest } = input;
+        const { name, args, arguments: argumentsAlias, project_id: _projectId, ...rest } = input;
         const unknownKeys = Object.keys(rest);
         if (unknownKeys.length > 0) {
-            return notFound(unknownKeyMessage(unknownKeys));
+            return notFound(unknownKeyMessage(unknownKeys), 'validation_failed');
         }
         if (args !== undefined && argumentsAlias !== undefined && JSON.stringify(args) !== JSON.stringify(argumentsAlias)) {
-            return notFound("Both 'args' and 'arguments' were provided with different values. Provide either 'args' or 'arguments', not both.");
+            return notFound("Both 'args' and 'arguments' were provided with different values. Provide either 'args' or 'arguments', not both.", 'validation_failed');
         }
         const effective = args ?? argumentsAlias ?? {};
         const catalog = await getCatalog();
@@ -157,7 +168,7 @@ export function registerGatewayTools(server, options) {
         }
         const unknownArgs = findUnknownArgKeys(entry.inputSchema, effective);
         if (unknownArgs.length > 0) {
-            return notFound(unknownArgsMessage(name, entry.inputSchema, unknownArgs));
+            return notFound(unknownArgsMessage(name, entry.inputSchema, unknownArgs), 'validation_failed');
         }
         return await catalog.client.callTool({ name, arguments: effective });
     });

package/build/tools/segments.js

@@ -297,7 +297,7 @@ export function registerSegmentTools(server) {
             model: getAnthropicModelId(),
             max_tokens: AI_MAX_TOKENS,
             ...outputConfig("low"),
-            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, email_sends. email_sends uses eq only and value {"min_count":4,"within_days":30}; both required, at most one per segment. It counts email_log rows with non-null sent_at in the inclusive elapsed-day window through now, regardless of current status. No observed sends = zero; failed history reads are errors. 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, email_sends. email_sends uses eq only and value {"min_count":4,"within_days":30}; both required, at most one per segment. It counts email_log rows with non-null sent_at in the inclusive elapsed-day window through now, regardless of current status. No observed sends = zero; failed history reads are errors. "tagged A and B AND never opened" means {"op":"AND","conditions":[{"field":"tags","operator":"contains","value":"A"},{"field":"tags","operator":"contains","value":"B"},{"field":"last_opened_at","operator":"not_exists"}],"exclude_suppressed":true}. Use one tags contains condition per required tag; never opened means last_opened_at not_exists (no value), not an unsupported activity field. 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 raw = anthropicCheckedText(resp);
@@ -308,8 +308,8 @@ export function registerSegmentTools(server) {
         catch (parseError) {
             // #4270: parsed rules that are missing or malformed are an error, never "everyone".
             if (isSegmentRulesError(parseError))
-                return txt(`Error: Could not use the rules parsed from "${description}". ${parseError.message}`);
-            return txt(`Error: Failed to parse rules from "${description}"`);
+                return toolError({ error: `Could not use the rules parsed from "${description}". ${parseError.message}`, code: 'validation_failed' });
+            return toolError({ error: `Failed to parse rules from "${description}"`, code: 'validation_failed' });
         }
         const ids = await getSegmentContactIds(parsedRules);
         const sample = ids.slice(0, 5);

package/package.json

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