@sendinel/mcp-server 1.0.144 → 1.0.146

package/build/lib/tags.d.ts

@@ -0,0 +1,10 @@
+/** Normalize input only: preserve first-seen spelling for exact-match consumers. */
+export declare function normalizeTagInput(input: string[]): {
+    tags: string[];
+    dropped_empty: number;
+    case_duplicates: {
+        kept: string;
+        dropped: string;
+    }[];
+};
+export declare function tagInputWarnings(result: ReturnType<typeof normalizeTagInput>): string[];

package/build/lib/tags.js

@@ -0,0 +1,29 @@
+/** Normalize input only: preserve first-seen spelling for exact-match consumers. */
+export function normalizeTagInput(input) {
+    const tags = [];
+    const seen = new Map();
+    let dropped_empty = 0;
+    const case_duplicates = [];
+    for (const value of input) {
+        const tag = value.trim();
+        if (!tag) {
+            dropped_empty++;
+            continue;
+        }
+        const key = tag.toLowerCase();
+        const kept = seen.get(key);
+        if (kept !== undefined) {
+            case_duplicates.push({ kept, dropped: tag });
+            continue;
+        }
+        seen.set(key, tag);
+        tags.push(tag);
+    }
+    return { tags, dropped_empty, case_duplicates };
+}
+export function tagInputWarnings(result) {
+    return [
+        ...(result.dropped_empty ? [`Dropped ${result.dropped_empty} empty tag(s).`] : []),
+        ...result.case_duplicates.map(({ kept, dropped }) => `Tag "${dropped}" duplicates "${kept}" (case-insensitive); kept "${kept}".`),
+    ];
+}

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

@@ -1,3 +1,4 @@
+import { normalizeTagInput, tagInputWarnings } from '../lib/tags.js';
 import { dbErrorResult } from '../lib/db-errors.js';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
@@ -493,8 +494,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 +963,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(),
@@ -1299,6 +1300,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             company_id: z.string().uuid().optional(),
             company_name: z.string().optional(),
             company_domain: z.string().optional(),
+            tags: z.array(z.string()).optional().describe('Initial tags for new subscribers; existing contacts keep their stored tags.'),
             source: z.enum(['signup', 'import', 'form', 'manual']).optional().default('manual'),
             utm_source: z.string().optional(),
             utm_medium: z.string().optional(),
@@ -1306,8 +1308,11 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             utm_content: z.string().optional(),
             utm_term: z.string().optional(),
         },
-    }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
+    }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, tags, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
         try {
+            const normalizedTags = normalizeTagInput(tags ?? []);
+            const warnings = tagInputWarnings(normalizedTags);
+            const tagWarnings = warnings.length ? { warnings } : {};
             email = email.trim().toLowerCase();
             const projectId = getProjectId();
             // Block distribution list / system addresses
@@ -1351,6 +1356,8 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             let contact;
             if (!existingContact) {
                 const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
+                if (tags !== undefined)
+                    row.tags = normalizedTags.tags;
                 if (customProperties)
                     row.custom_properties = customProperties;
                 if (!needsConfirm)
@@ -1426,15 +1433,15 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             if (needsConfirm) {
                 // Create opt-in token (confirmation email must be sent externally in MCP context)
                 await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
-                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
+                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}) });
                 logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
-                return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
+                return { content: [{ type: 'text', text: JSON.stringify({ ...contact, ...tagWarnings, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
             }
-            await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
+            await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}) });
             logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
             if (!existing)
                 logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
-            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, ...tagWarnings, existing, ...existingMessage }, null, 2) }] };
         }
         catch (error) {
             return dbErrorResult(error);
@@ -1815,6 +1822,9 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
     }, async ({ contact_id, email, first_name, last_name, company_id, company_name, company_domain, tags, custom_properties, phone_e164, timezone }) => {
         try {
             const projectId = getProjectId();
+            const normalizedTags = tags !== undefined ? normalizeTagInput(tags) : undefined;
+            if (normalizedTags)
+                tags = normalizedTags.tags;
             let propertyWarnings = [];
             let fields;
             if (custom_properties !== undefined) {
@@ -2000,7 +2010,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 ...(updates.tags !== undefined ? { tags: updates.tags } : {}),
                 ...(updates.custom_properties !== undefined ? { custom_properties: updates.custom_properties } : {}),
             });
-            const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings];
+            const mergedWarnings = [...(tagResult.warnings ?? []), ...propertyWarnings, ...(normalizedTags ? tagInputWarnings(normalizedTags) : [])];
             return j({ ...data, ...tagResult, ...(mergedWarnings.length ? { warnings: mergedWarnings } : {}) });
         }
         catch (error) {
@@ -2136,57 +2146,78 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Add or remove tags from one or more contacts',
+        description: 'Add or remove tags from one or more contacts. Tags are trimmed; empty values are ignored; case variants of an existing tag are not added again. Removal is case-insensitive. Ids not found are returned in not_found.',
         inputSchema: {
             contact_ids: z.array(z.string().uuid()).min(1),
             add_tags: z.array(z.string()).optional(),
             remove_tags: z.array(z.string()).optional(),
         },
     }, async ({ contact_ids, add_tags = [], remove_tags = [] }) => {
+        const normalized = normalizeTagInput(add_tags);
+        add_tags = normalized.tags;
+        remove_tags = remove_tags.map(tag => tag.trim()).filter(Boolean);
+        const warnings = new Set(tagInputWarnings(normalized));
         if (!add_tags.length && !remove_tags.length)
             return toolError({ error: 'No tags to add or remove.', code: 'validation_failed' });
         const projectId = getProjectId();
         let updated = 0;
         const missing_contact_ids = [];
+        const failed = [];
         for (const cid of contact_ids) {
-            const { data: contact, error: readError } = await db()
-                .from('subscribers')
-                .select('id, email, first_name, last_name, custom_properties, tags')
-                .eq('id', cid)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            if (readError)
-                return toolError({ ...dbToolError(readError), updated });
-            if (!contact) {
-                missing_contact_ids.push(cid);
-                continue;
-            }
-            const currentTags = contact.tags ?? [];
-            const removeSet = new Set(remove_tags);
-            const merged = currentTags.filter((t) => !removeSet.has(t));
-            for (const t of add_tags) {
-                if (!merged.includes(t))
-                    merged.push(t);
+            try {
+                const { data: contact, error: readError } = await db()
+                    .from('subscribers')
+                    .select('id, email, first_name, last_name, custom_properties, tags')
+                    .eq('id', cid)
+                    .eq('project_id', projectId)
+                    .maybeSingle();
+                if (readError) {
+                    failed.push({ id: cid, ...dbToolError(readError) });
+                    continue;
+                }
+                if (!contact) {
+                    missing_contact_ids.push(cid);
+                    continue;
+                }
+                const currentTags = contact.tags ?? [];
+                const removeSet = new Set(remove_tags.map(tag => tag.toLowerCase()));
+                const merged = currentTags.filter((t) => !removeSet.has(t.trim().toLowerCase()));
+                for (const tag of add_tags) {
+                    const existing = merged.find(value => value.trim().toLowerCase() === tag.toLowerCase());
+                    if (existing !== undefined)
+                        warnings.add(`${tag} already exists as ${existing}`);
+                    else
+                        merged.push(tag);
+                }
+                const { data: saved, error } = await db()
+                    .from('subscribers')
+                    .update({ tags: merged })
+                    .eq('id', cid)
+                    .eq('project_id', projectId)
+                    .select('id').maybeSingle();
+                if (error) {
+                    failed.push({ id: cid, ...dbToolError(error) });
+                    continue;
+                }
+                if (!saved) {
+                    missing_contact_ids.push(cid);
+                    continue;
+                }
+                updated++;
+                await writeBackMcpContact(projectId, contact, { tags: merged });
+                await logAudit({ action: 'subscriber.tags_updated', resourceType: 'subscriber', resourceId: cid, details: { add_tags, remove_tags } });
             }
-            const { data: saved, error } = await db()
-                .from('subscribers')
-                .update({ tags: merged })
-                .eq('id', cid)
-                .eq('project_id', projectId)
-                .select('id').maybeSingle();
-            if (error)
-                return toolError({ ...dbToolError(error), updated });
-            if (!saved) {
-                missing_contact_ids.push(cid);
-                continue;
+            catch {
+                failed.push({ id: cid, ...dbToolError({}) });
             }
-            updated++;
-            await writeBackMcpContact(projectId, contact, { tags: merged });
-            await logAudit({ action: 'subscriber.tags_updated', resourceType: 'subscriber', resourceId: cid, details: { add_tags, remove_tags } });
         }
+        const result = { missing_contact_ids, not_found: missing_contact_ids, failed, updated, total: contact_ids.length, add_tags, remove_tags, ...(warnings.size ? { warnings: [...warnings] } : {}) };
+        // Preserve the existing coded-error convention when no requested write succeeded.
+        if (!updated && failed.length)
+            return toolError({ ...dbToolError({}), ...result, code: failed[0].code, error: failed[0].error });
         if (!updated)
-            return toolError({ error: 'Subscriber not found', code: 'not_found', updated, missing_contact_ids });
-        return j({ missing_contact_ids, updated, total: contact_ids.length, add_tags, remove_tags });
+            return toolError({ error: 'Subscriber not found', code: 'not_found', ...result });
+        return j(result);
     });
     server.registerTool('bulk_update_subscribers', {
         title: 'Bulk Update Subscribers',

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.146",
   "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",