@sendinel/mcp-server 1.0.215 → 1.0.217

package/build/lib/action-approvals.d.ts

@@ -1,4 +1,5 @@
 import type { DecisionEvidence } from './approval-elicitation-evidence.js';
+import { type AutoApproveUnavailableReason } from './sandbox-approvals.js';
 export { isApprovalGatedAction } from './approval-actions.js';
 /**
  * Action approval tiers:
@@ -35,8 +36,9 @@ export declare function assertChannelCanExecute(action: string, params: Record<s
 /** Convenience: pull channel/verified out of the request-scoped context, defaulting to today's only live caller (mcp_api_key). */
 export declare function currentChannelContext(): ChannelExecutionContext;
 /**
- * Display-only facts for the approval summary (segment name, count, subject, excerpt). Never
- * stored in params, so it can't change the params an approval is checked against.
+ * Display-only facts for the approval summary (segment name, count, subject, excerpt).
+ * merge_variable_summary is frozen in __approval_snapshot.display; the other facts
+ * do not change the params an approval is checked against.
  */
 export type ApprovalDisplay = Record<string, string | number | null | undefined>;
 /** Tag-stripped, whitespace-collapsed, length-capped text. HTML is untrusted input. */
@@ -45,6 +47,7 @@ export declare function approvalExcerpt(html: unknown, max?: number): string;
 export declare function buildApprovalSummary(action: string, params: Record<string, unknown>, display?: ApprovalDisplay): string;
 export interface ApprovalResult {
     requires_approval: true;
+    auto_approve_unavailable_reason?: AutoApproveUnavailableReason;
     approval_id: string;
     tier: ApprovalTier;
     action: string;

package/build/lib/action-approvals.js

@@ -1,5 +1,5 @@
 import { effectiveApproval, auditApprovalLevel } from './approval-classes.js';
-import { sandboxApprovalEligible, trySandboxApproval } from './sandbox-approvals.js';
+import { sandboxApprovalEligible, trySandboxApprovalWithReason } from './sandbox-approvals.js';
 import { humanApprovalEligible } from './approval-human-eligibility.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
@@ -252,8 +252,10 @@ export function buildApprovalSummary(action, params, display = {}) {
         remove_suppression: (p) => `Remove ${p.email} from the suppression list — mail to this address will resume`,
     };
     const fn = summaries[action];
-    if (fn)
-        return fn(params);
+    if (fn) {
+        const line = params.__approval_snapshot?.display?.merge_variable_summary;
+        return fn(params) + (line ? `\n${line}` : '');
+    }
     const payload = JSON.stringify(normalizeApprovalParams(params));
     return `Execute ${action} with: ${payload.length > 400 ? `${payload.slice(0, 399)}…` : payload}`;
 }
@@ -356,6 +358,9 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
     const cleanParams = withoutApprovalSnapshot(params);
     const snapshot = { ...await captureSnapshot(action, cleanParams), ...(effective.applied ? { approval_class: effective.class, approval_channel_rule: effective.channelRule } : {}),
         ...(display && 'recipient_count' in display ? { display_recipient_count: display.recipient_count } : {}) };
+    if (typeof display?.merge_variable_summary === 'string') {
+        snapshot.display = { ...snapshot.display, merge_variable_summary: display.merge_variable_summary };
+    }
     const payload = cleanParams.payload;
     if (action === 'send_broadcast' && Array.isArray(payload?.contact_ids) && Array.isArray(snapshot.contact_ids) &&
         !approvalParamsEqual({ ids: [...payload.contact_ids].sort() }, { ids: snapshot.contact_ids })) {
@@ -392,7 +397,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         throw new Error(`Failed to create approval request: ${error.message}`);
     let projectName;
     let sandboxDisplayRead = false;
-    const sandboxApproved = !(effective.applied && (effective.level === 'ask_every_time' || (effective.class === 'F' && !action.startsWith('delete_')))) && await trySandboxApproval(data.id, getProjectId(), action, approvalPayloadHash(action, frozenParams), name => { projectName = name; sandboxDisplayRead = true; }, frozenParams);
+    const sandboxPolicyBlocked = effective.applied && (effective.level === 'ask_every_time' || (effective.class === 'F' && !action.startsWith('delete_')));
+    const sandboxAttempt = sandboxPolicyBlocked ? { approved: false, reason: 'approval_policy' } : await trySandboxApprovalWithReason(data.id, getProjectId(), action, approvalPayloadHash(action, frozenParams), name => { projectName = name; sandboxDisplayRead = true; }, frozenParams);
     if (isTesterRequest(action))
         await logTesterRequestAudit('tester_request', action, data.id, null);
     fireWebhookEvent('approval.requested', {
@@ -414,16 +420,18 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         catch { /* Missing display data omits the project line. */ }
     const approveUrl = approvalPageUrl(data.id);
     const previewText = buildApprovalPreview({ action, params: frozenParams, summary: detailSummary, projectName, ...(display && 'recipient_count' in display ? { recipientCount: display.recipient_count } : {}) }).plain_summary;
-    if (sandboxApproved) {
+    if (sandboxAttempt.approved) {
         return { requires_approval: true, approval_id: data.id, tier, action, summary, expires_at: expiresAt,
             approve_via: 'sandbox', decided_via: 'sandbox', decided_by: null, approve_url: approveUrl, preview_text: previewText, decision_status: 'approved',
             message: approvalNext(action, { approve_via: 'sandbox', decision_status: 'approved' }) };
     }
+    const autoApproveUnavailableReason = sandboxAttempt.reason;
     const chatGuidance = tier === 'gated' && await humanApprovalEligible(action, getProjectId(), actor, true)
         ? `\nAsk the user in plain chat: "${previewText.split('\n')[0].trim()}". Only after they say yes, call confirm_approval with approval_id, action, echo (the first line of preview_text) and user_reply (their exact words), then ${approvalRetryInstruction(action)}`
         : '';
     const result = await elicitApproval({
         requires_approval: true,
+        auto_approve_unavailable_reason: autoApproveUnavailableReason,
         ...(effective.channelRule === 'human_only' ? {} : await offerApprovalApp({ id: data.id, action, params: frozenParams, summary, tier, expires_at: expiresAt,
             payload_hash: approvalPayloadHash(action, frozenParams) })),
         approval_id: data.id,

package/build/lib/content-sources.d.ts

@@ -1,4 +1,4 @@
-import { type ContentIssue } from '@sendinel/domain';
+import { type MergeVariableWarning, type ContentIssue } from '@sendinel/domain';
 /** Data keys seen on an event in the project's history, or null when the lookup failed. */
 export declare function eventKeysFromHistory(projectId: string, eventName: string): Promise<string[] | null>;
 /**
@@ -32,7 +32,9 @@ export type CampaignContentFinding = ContentIssue & {
  * every email of the given campaigns (#3853). Placeholder text and sending-domain links are
  * blocking; merge-tag findings are warnings. A failed lookup is reported as a warning, never as a pass.
  */
-export declare function checkCampaignContent(projectId: string, campaigns: ContentCampaign[], steps: ContentStep[]): Promise<{
+export declare function checkCampaignContent(projectId: string, campaigns: ContentCampaign[], steps: ContentStep[], options?: {
+    mergeVariables?: boolean;
+}): Promise<{
     blocking: CampaignContentFinding[];
     warnings: CampaignContentFinding[];
     lookup_errors: string[];
@@ -59,4 +61,22 @@ export declare function summarizeContentWarnings(warnings: Array<{
     email?: number;
     warning: string;
 }>): string;
+export type CampaignMergeVariableWarning = MergeVariableWarning & {
+    step_order: number;
+    checked_at: string;
+    warning: string;
+};
+/** Uses the shared domain rules; unavailable sources stay unknown and never stop activation. */
+export declare function checkCampaignMergeVariables(projectId: string, campaign: {
+    trigger_event_name: string | null;
+}, steps: Array<{
+    step_order: number;
+    subject?: string | null;
+    body_html?: string | null;
+    body_text?: string | null;
+}>): Promise<CampaignMergeVariableWarning[]>;
+/** One extra line on the approval, including explicit uncertainty for unknown sources. */
+export declare function summarizeMergeVariableWarnings(warnings: CampaignMergeVariableWarning[]): string | undefined;
+/** Best-effort note. Compare-and-swap preserves concurrent metadata edits; never gate activation. */
+export declare function persistMergeVariableWarnings(projectId: string, campaignId: string, warnings: CampaignMergeVariableWarning[]): Promise<void>;
 export {};

package/build/lib/content-sources.js

@@ -1,4 +1,4 @@
-import { BLOCKING_CONTENT_ISSUE_KINDS, findContentIssues, sendingHostOf } from '@sendinel/domain';
+import { BLOCKING_CONTENT_ISSUE_KINDS, findContentIssues, sendingHostOf, findUnprovidedMergeTags } from '@sendinel/domain';
 import { db } from '../db.js';
 /** Data keys seen on an event in the project's history, or null when the lookup failed. */
 export async function eventKeysFromHistory(projectId, eventName) {
@@ -50,7 +50,7 @@ export async function contactPropertyKeys(projectId) {
  * every email of the given campaigns (#3853). Placeholder text and sending-domain links are
  * blocking; merge-tag findings are warnings. A failed lookup is reported as a warning, never as a pass.
  */
-export async function checkCampaignContent(projectId, campaigns, steps) {
+export async function checkCampaignContent(projectId, campaigns, steps, options = {}) {
     const lookupErrors = [];
     const sendingHostsBySite = new Map();
     const allHosts = new Set();
@@ -63,11 +63,11 @@ export async function checkCampaignContent(projectId, campaigns, steps) {
         for (const host of hosts)
             allHosts.add(host);
     }
-    const contactProps = await contactPropertyKeys(projectId);
-    if (contactProps === null)
+    const contactProps = options.mergeVariables === false ? null : await contactPropertyKeys(projectId);
+    if (options.mergeVariables !== false && contactProps === null)
         lookupErrors.push('Could not read your contacts, so merge tags that use contact properties were not confirmed.');
     const eventKeys = new Map();
-    for (const eventName of new Set(campaigns.map((c) => c.trigger_event_name).filter((e) => Boolean(e)))) {
+    for (const eventName of new Set((options.mergeVariables === false ? [] : campaigns).map((c) => c.trigger_event_name).filter((e) => Boolean(e)))) {
         const keys = await eventKeysFromHistory(projectId, eventName);
         eventKeys.set(eventName, keys);
         if (keys === null)
@@ -82,7 +82,7 @@ export async function checkCampaignContent(projectId, campaigns, steps) {
             : [...events, ...contactProps.keys.map((key) => `custom.${key}`)];
         const hosts = (campaign.site_id ? sendingHostsBySite.get(campaign.site_id) : undefined) ?? [...allHosts];
         for (const step of steps.filter((s) => s.campaign_id === campaign.id)) {
-            for (const issue of findContentIssues(step, { sendingHosts: hosts, sourcedKeys })) {
+            for (const issue of findContentIssues(step, { sendingHosts: hosts, sourcedKeys: options.mergeVariables === false ? undefined : sourcedKeys })) {
                 const finding = { ...issue, campaign: campaign.name, email: step.step_order + 1 };
                 (BLOCKING_CONTENT_ISSUE_KINDS.has(issue.kind) ? blocking : warnings).push(finding);
             }
@@ -109,3 +109,60 @@ export function summarizeContentWarnings(warnings) {
     const first = warnings.slice(0, 3).map((w) => (w.campaign ? `${w.campaign}, email ${w.email}: ${w.warning}` : w.warning));
     return `${warnings.length} warning${warnings.length === 1 ? '' : 's'}. ${first.join(' | ')}${warnings.length > 3 ? ` | and ${warnings.length - 3} more` : ''}`;
 }
+/** Uses the shared domain rules; unavailable sources stay unknown and never stop activation. */
+export async function checkCampaignMergeVariables(projectId, campaign, steps) {
+    const safe = async (load) => {
+        try {
+            return await load();
+        }
+        catch {
+            return null;
+        }
+    };
+    const contacts = await safe(() => contactPropertyKeys(projectId));
+    const events = campaign.trigger_event_name
+        ? await safe(() => eventKeysFromHistory(projectId, campaign.trigger_event_name)) : [];
+    const knowledge = {
+        eventKeys: events === null ? null : new Set(events),
+        contactPropertyKeys: contacts === null ? null : { keys: new Set(contacts.keys), complete: contacts.complete },
+    };
+    const checked_at = new Date().toISOString();
+    return steps.flatMap(step => findUnprovidedMergeTags({ subject: step.subject, html: step.body_html, text: step.body_text }, knowledge).map(finding => ({ ...finding, step_order: step.step_order, checked_at,
+        warning: finding.kind === 'unknown_event'
+            ? `Can't tell whether ${finding.tag} can be filled: event history is empty or couldn't be checked.`
+            : finding.kind === 'unknown_contacts'
+                ? `Couldn't check whether ${finding.tag} can be filled: the contact scan failed or is incomplete.`
+                : `${finding.tag} may print blank: ${finding.kind === 'no_event_data' ? 'no observed trigger event data provides it' : 'no contact has this property'}.`,
+    })));
+}
+/** One extra line on the approval, including explicit uncertainty for unknown sources. */
+export function summarizeMergeVariableWarnings(warnings) {
+    if (!warnings.length)
+        return undefined;
+    return `${warnings.length} merge variables may print blank: ${warnings.map(w => `${w.tag} (email ${w.step_order + 1}${w.kind.startsWith('unknown_') ? ": can't tell / couldn't check" : ''})`).join(', ')}`;
+}
+/** Best-effort note. Compare-and-swap preserves concurrent metadata edits; never gate activation. */
+export async function persistMergeVariableWarnings(projectId, campaignId, warnings) {
+    try {
+        const source = db().schema('email');
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const { data: current, error: readError } = await source.from('campaigns').select('metadata')
+                .eq('id', campaignId).eq('project_id', projectId).maybeSingle();
+            if (readError || !current)
+                break;
+            const metadata = current.metadata;
+            const next = { ...(metadata ?? {}), merge_variable_warnings: warnings
+                    .filter(w => w.kind === 'no_event_data' || w.kind === 'no_contact_has_it')
+                    .map(({ tag, step_order, kind, checked_at }) => ({ tag, step_order, kind, checked_at })) };
+            let update = source.from('campaigns').update({ metadata: next }).eq('id', campaignId).eq('project_id', projectId);
+            update = metadata == null ? update.is('metadata', null) : update.eq('metadata', JSON.stringify(metadata));
+            const { data, error } = await update.select('id');
+            if (error)
+                break;
+            if (data?.length)
+                return;
+        }
+    }
+    catch { /* A failed note write must not prevent activation. */ }
+    console.error('[merge-variable-warnings] Could not save campaign warning note.');
+}

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

@@ -8,6 +8,18 @@ const projectRule = 'On hosted /mcp, pass project_id on each call. It is require
 const previewRule = 'preview_email uses the real send renderer with sample contact data. send_test_email with dry_run:true uses the real renderer without sending or needing approval, including in standard mode. Stdio requires SENDINEL_API_KEY.';
 const sender = { n: 1, tool: 'get_sites', args_example: {}, note: 'Choose the intended sender from the returned array; do not assume the first sender is correct. Replace example content and addresses with the user’s own choices.' };
 export const HOW_TO_RECIPES = [
+    {
+        id: 'clean-up-test-objects', title: 'Clean up sandbox test contacts and objects',
+        when_to_use: 'Remove throwaway contacts or objects created by this credential after a sandbox test.',
+        synonyms: TOOL_ALIASES.delete_subscriber_data,
+        requires: { scopes: ['admin'], tester_ok: false },
+        steps: [
+            { n: 1, tool: 'delete_subscriber_data', args_example: { contact_id: '11111111-1111-4111-8111-111111111111', reason: 'admin' }, approval, note: 'Replace contact_id with the saved ID of a test contact you created. This is irreversible GDPR erasure, including related data. In a sandbox project, same-credential provenance permits automatic approval; inspect decision_status and auto_approve_unavailable_reason. If pending, show approve_url and wait for human approval.' },
+            { n: 2, tool: 'delete_subscriber_data', args_example: { approval_id: from(1, 'approval_id') }, approval, note: 'Only after decision_status is approved, re-call with ONLY approval_id to execute. Repeat for each intended test contact.' },
+        ],
+        gotchas: [projectRule, 'is_test:true is only a contact classification, never delete authority. Non-sandbox projects keep human approval. Unknown or foreign provenance stays gated. Campaign cleanup uses delete_campaign with campaign_id; every cascading step must also belong to this credential. Templates and segments use delete_template with id and delete_segment with segment_id, with the same approval_id flow.'],
+        done_when: 'Each intended cleanup execution succeeds; automatic approval alone has not deleted anything.',
+    },
     {
         id: 'brand-kit-signature', title: 'Preview and save a brand-kit email signature',
         when_to_use: 'Set up or edit a signature footer for future AI-generated drafts using stored brand details.',

package/build/lib/mcp-created-items.d.ts

@@ -25,4 +25,7 @@ export declare function withCreatedItems<T extends {
     error: any;
 }>(entityType: CreatedItemType, query: PromiseLike<T>): Promise<T>;
 /** Unknown actions/targets and partial reads fail closed, including defensive bulk inputs. */
+export type DeleteOwnershipUnavailableReason = 'not_created_by_this_credential' | 'unknown_provenance';
+export declare function deleteOwnershipUnavailableReason(projectId: string, action: string, params: Record<string, unknown>, creatorKey: string | null): Promise<DeleteOwnershipUnavailableReason | null>;
+/** Preserve the boolean authority API; diagnostics never supply another approval path. */
 export declare function ownsDeleteTargets(projectId: string, action: string, params: Record<string, unknown>, creatorKey: string | null): Promise<boolean>;

package/build/lib/mcp-created-items.js

@@ -54,11 +54,10 @@ export async function withCreatedItems(entityType, query) {
     return result;
 }
 const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** Unknown actions/targets and partial reads fail closed, including defensive bulk inputs. */
-export async function ownsDeleteTargets(projectId, action, params, creatorKey) {
+export async function deleteOwnershipUnavailableReason(projectId, action, params, creatorKey) {
     const target = DELETE_ITEM_TARGETS[action];
     if (!creatorKey || !target)
-        return false;
+        return 'unknown_provenance';
     const [entityType, single, bulk] = target;
     const source = adminDb().schema('email');
     let ids = [];
@@ -66,36 +65,46 @@ export async function ownsDeleteTargets(projectId, action, params, creatorKey) {
         ids.push(params[single]);
     if (params[bulk] !== undefined) {
         if (!Array.isArray(params[bulk]) || !params[bulk].length)
-            return false;
+            return 'unknown_provenance';
         ids.push(...params[bulk]);
     }
     // GDPR snapshots carry both ID and email. Verify the address names that same target.
     if (action === 'delete_subscriber_data' && params.email !== undefined) {
         if (typeof params.email !== 'string' || !params.email.trim())
-            return false;
+            return 'unknown_provenance';
         const { data, error } = await source.from('subscribers').select('id').eq('project_id', projectId)
             .eq('email', params.email.trim().toLowerCase()).maybeSingle();
         if (error || !data || (ids.length && (ids.length !== 1 || ids[0] !== data.id)))
-            return false;
+            return 'unknown_provenance';
         ids.push(data.id);
     }
     if (!ids.length || ids.some(id => typeof id !== 'string' || !uuid.test(id)))
-        return false;
+        return 'unknown_provenance';
     ids = [...new Set(ids)];
     const owns = async (type, targets) => {
-        const { data, error } = await source.from('mcp_created_items').select('entity_id')
-            .eq('project_id', projectId).eq('entity_type', type).eq('creator_key', creatorKey).in('entity_id', targets);
-        return !error && Array.isArray(data) && targets.every(id => data.some(row => row.entity_id === id));
+        const { data, error } = await source.from('mcp_created_items').select('entity_id, creator_key')
+            .eq('project_id', projectId).eq('entity_type', type).in('entity_id', targets);
+        if (error || !Array.isArray(data))
+            return 'unknown_provenance';
+        if (targets.some(id => !data.some(row => row.entity_id === id && typeof row.creator_key === 'string')))
+            return 'unknown_provenance';
+        return targets.every(id => data.some(row => row.entity_id === id && row.creator_key === creatorKey))
+            ? null : 'not_created_by_this_credential';
     };
-    if (!await owns(entityType, ids))
-        return false;
+    const reason = await owns(entityType, ids);
+    if (reason)
+        return reason;
     // Deleting a campaign also deletes its steps; another client may have added one.
     if (action === 'delete_campaign') {
         const { data, error } = await source.from('campaign_steps').select('id').in('campaign_id', ids);
         if (error || !Array.isArray(data))
-            return false;
-        if (data.length && !await owns('campaign_steps', data.map(row => row.id)))
-            return false;
+            return 'unknown_provenance';
+        if (data.length)
+            return await owns('campaign_steps', data.map(row => row.id));
     }
-    return true;
+    return null;
+}
+/** Preserve the boolean authority API; diagnostics never supply another approval path. */
+export async function ownsDeleteTargets(projectId, action, params, creatorKey) {
+    return await deleteOwnershipUnavailableReason(projectId, action, params, creatorKey) === null;
 }

package/build/lib/sandbox-approvals.d.ts

@@ -26,6 +26,14 @@ export declare const SANDBOX_ADMIN_SCOPE: {
     readonly set_team_member_role: 'org';
     readonly tenant_export_full: 'project';
 };
+export type AutoApproveUnavailableReason = 'not_sandbox' | 'not_created_by_this_credential' | 'unknown_provenance' | 'action_not_eligible' | 'org_not_all_sandbox' | 'approval_policy' | 'auto_approval_failed';
 /** Never consult token claims, BYOD clients or cached display data for this authority. */
+export declare function sandboxAutoApproveUnavailableReason(projectId: string, action: string, onProjectRead?: (name: string | undefined) => void, params?: Record<string, unknown>): Promise<AutoApproveUnavailableReason | null>;
+/** Existing callers keep their boolean contract and the same fail-closed conditions. */
 export declare function sandboxApprovalEligible(projectId: string, action: string, onProjectRead?: (name: string | undefined) => void, params?: Record<string, unknown>): Promise<boolean>;
+/** Capture the refusal from the same attempt, without a second mutable authority read. */
+export declare function trySandboxApprovalWithReason(id: string, projectId: string, action: string, payloadHash: string, onProjectRead?: (name: string | undefined) => void, params?: Record<string, unknown>): Promise<{
+    approved: boolean;
+    reason?: AutoApproveUnavailableReason;
+}>;
 export declare function trySandboxApproval(id: string, projectId: string, action: string, payloadHash: string, onProjectRead?: (name: string | undefined) => void, params?: Record<string, unknown>): Promise<boolean>;

package/build/lib/sandbox-approvals.js

@@ -1,5 +1,5 @@
 import { adminDb } from '../db.js';
-import { DELETE_ITEM_TARGETS, ownsDeleteTargets, requestingCreatorKey } from './mcp-created-items.js';
+import { DELETE_ITEM_TARGETS, deleteOwnershipUnavailableReason, requestingCreatorKey } from './mcp-created-items.js';
 import { approvalClass } from '@sendinel/domain';
 import { PROTECTED_ACTIONS } from './approval-actions.js';
 import { isHumanRequestableAdminTool } from './admin-tools.js';
@@ -16,48 +16,63 @@ export const SANDBOX_ADMIN_SCOPE = {
     tenant_export_full: 'project',
 };
 /** Never consult token claims, BYOD clients or cached display data for this authority. */
-export async function sandboxApprovalEligible(projectId, action, onProjectRead, params = {}) {
+export async function sandboxAutoApproveUnavailableReason(projectId, action, onProjectRead, params = {}) {
     const deletion = approvalClass(action) === 'D' || action.startsWith('delete_');
     // No exception for shared org credentials, unknown delete actions or other protected effects.
-    if (deletion && (!(action in DELETE_ITEM_TARGETS) || !requestingCreatorKey()))
-        return false;
+    if (deletion && !(action in DELETE_ITEM_TARGETS))
+        return 'action_not_eligible';
+    if (deletion && !requestingCreatorKey())
+        return 'unknown_provenance';
     if (action === 'delete_provider_credential' || (!deletion && PROTECTED_ACTIONS.has(action)))
-        return false;
+        return 'action_not_eligible';
     try {
         const source = adminDb().schema('email');
         const { data, error } = await source.from('projects').select('id, org_id, sandbox_mode, name')
             .eq('id', projectId).maybeSingle();
         onProjectRead?.(!error && typeof data?.name === 'string' ? data.name : undefined);
-        if (error || data?.id !== projectId || data.sandbox_mode !== true)
-            return false;
+        if (error || data?.id !== projectId)
+            return 'unknown_provenance';
+        if (data.sandbox_mode !== true)
+            return 'not_sandbox';
         if (deletion)
-            return await ownsDeleteTargets(projectId, action, params, requestingCreatorKey());
+            return await deleteOwnershipUnavailableReason(projectId, action, params, requestingCreatorKey());
         if (!isHumanRequestableAdminTool(action))
-            return true;
+            return null;
         const scope = SANDBOX_ADMIN_SCOPE[action];
         if (scope === 'project')
-            return true;
+            return null;
         if (scope !== 'org' || typeof data.org_id !== 'string')
-            return false;
+            return 'action_not_eligible';
         const others = await source.from('projects').select('id').eq('org_id', data.org_id)
             .eq('sandbox_mode', false).limit(1);
-        return !others.error && Array.isArray(others.data) && others.data.length === 0;
+        if (others.error || !Array.isArray(others.data))
+            return 'unknown_provenance';
+        return others.data.length === 0 ? null : 'org_not_all_sandbox';
     }
     catch {
-        return false;
+        return 'unknown_provenance';
     }
 }
-export async function trySandboxApproval(id, projectId, action, payloadHash, onProjectRead, params = {}) {
-    if (!await sandboxApprovalEligible(projectId, action, onProjectRead, params))
-        return false;
+/** Existing callers keep their boolean contract and the same fail-closed conditions. */
+export async function sandboxApprovalEligible(projectId, action, onProjectRead, params = {}) {
+    return await sandboxAutoApproveUnavailableReason(projectId, action, onProjectRead, params) === null;
+}
+/** Capture the refusal from the same attempt, without a second mutable authority read. */
+export async function trySandboxApprovalWithReason(id, projectId, action, payloadHash, onProjectRead, params = {}) {
+    const reason = await sandboxAutoApproveUnavailableReason(projectId, action, onProjectRead, params);
+    if (reason)
+        return { approved: false, reason };
     try {
         // The RPC performs one conditional UPDATE + audit INSERT in one transaction.
         const { data, error } = await adminDb().schema('email').rpc('approve_sandbox_action', {
             p_approval_id: id, p_project_id: projectId, p_action: action, p_payload_hash: payloadHash,
         });
-        return !error && data === true;
-    }
-    catch {
-        return false;
+        if (!error && data === true)
+            return { approved: true };
     }
+    catch { /* An RPC failure never grants authority. */ }
+    return { approved: false, reason: 'auto_approval_failed' };
+}
+export async function trySandboxApproval(id, projectId, action, payloadHash, onProjectRead, params = {}) {
+    return (await trySandboxApprovalWithReason(id, projectId, action, payloadHash, onProjectRead, params)).approved;
 }

package/build/tools/campaign-sets.js

@@ -11,7 +11,7 @@ import { generateEmailFromBrief } from '../lib/email-generation.js';
 import { fireWebhookEvent } from '../lib/webhook-events.js';
 import { logAudit } from '../audit.js';
 import { applyCampaignTargetingFields, campaignTriggerKind } from './campaigns.js';
-import { checkCampaignContent, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
+import { checkCampaignMergeVariables, persistMergeVariableWarnings, summarizeMergeVariableWarnings, checkCampaignContent, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
 import { captureBroadcastAudience } from '../lib/approval-snapshot.js';
 import { dbToolError } from '../lib/db-error.js';
 /**
@@ -291,9 +291,11 @@ export function registerCampaignSetTools(server) {
         const projectId = getProjectId();
         const { approval_id } = args;
         async function applyCampaigns(set, ids, approval_id, decidedBy) {
+            const mergeVariableWarnings = [];
             const activated = [];
             const failed = [];
             for (const c of set.campaigns) {
+                const warnings = await checkCampaignMergeVariables(projectId, c, set.steps.filter(s => s.campaign_id === c.id));
                 const { error } = await db()
                     .from('campaigns')
                     .update({ status: 'active', updated_at: new Date().toISOString() })
@@ -305,12 +307,15 @@ export function registerCampaignSetTools(server) {
                     continue;
                 }
                 activated.push(c.id);
+                await persistMergeVariableWarnings(projectId, c.id, warnings);
+                mergeVariableWarnings.push(...warnings.map(w => ({ ...w, campaign_id: c.id })));
                 fireWebhookEvent('campaign.activated', { campaign_id: c.id, campaign_name: c.name, status: 'active' }).catch(() => { });
             }
             await logAudit({ action: 'campaign.set_activated', resourceType: 'campaign_set', resourceId: approval_id, details: { approval_id, decided_by: decidedBy ?? null, activated, failed, source: 'mcp' } }).catch(() => { });
             return j({
                 activated,
                 failed,
+                merge_variable_warnings: mergeVariableWarnings,
                 ...(set.campaigns.some(c => c.type === 'broadcast') ? {
                     campaigns: previewOf(set.campaigns.filter(c => activated.includes(c.id)).map(c => ({ ...c, status: 'active' })), set.steps),
                     broadcast_activation: BROADCAST_ACTIVATION,
@@ -348,7 +353,7 @@ export function registerCampaignSetTools(server) {
                 return j({ error: 'this campaign has no trigger, so it would never fire', code: 'validation_failed' });
             }
             // Same content gate as the request, so a bad email can't ride through on an old approval.
-            const readiness = await checkCampaignContent(projectId, current.campaigns, current.steps);
+            const readiness = await checkCampaignContent(projectId, current.campaigns, current.steps, { mergeVariables: false });
             if (readiness.blocking.length)
                 return j(contentNotReadyResponse(readiness.blocking));
             const check = await checkApproval(approval_id, { consume: true, action: 'activate_campaigns', params: stored });
@@ -396,10 +401,12 @@ export function registerCampaignSetTools(server) {
             });
         }
         // Placeholder text and links to the sending domain never go out (#3853). Merge tags with no data source are warnings.
-        const readiness = await checkCampaignContent(projectId, set.campaigns, set.steps);
+        const readiness = await checkCampaignContent(projectId, set.campaigns, set.steps, { mergeVariables: false });
         if (readiness.blocking.length)
             return j(contentNotReadyResponse(readiness.blocking));
         const contentWarnings = contentWarningView(readiness.warnings, readiness.lookup_errors);
+        const mergeVariableWarnings = (await Promise.all(set.campaigns.map(async (c) => (await checkCampaignMergeVariables(projectId, c, set.steps.filter(s => s.campaign_id === c.id)))
+            .map(w => ({ ...w, campaign_id: c.id }))))).flat();
         const approvalParams = { campaign_ids: [...ids].sort(), content_hash: campaignSetContentHash(set.campaigns, set.steps) };
         const channelContext = currentChannelContext();
         const decision = await assertChannelCanExecute('activate_campaigns', approvalParams, channelContext);
@@ -409,6 +416,7 @@ export function registerCampaignSetTools(server) {
             return applyCampaigns(set, ids);
         const names = set.campaigns.map((c) => c.name);
         const approval = await requestApproval('activate_campaigns', approvalParams, undefined, channelContext, {
+            merge_variable_summary: summarizeMergeVariableWarnings(mergeVariableWarnings),
             campaign_count: set.campaigns.length,
             email_count: set.steps.length,
             campaign_names: names.slice(0, 10).join(', ') + (names.length > 10 ? `, and ${names.length - 10} more` : ''),
@@ -417,6 +425,7 @@ export function registerCampaignSetTools(server) {
         return j({
             ...approval,
             campaigns: previewOf(set.campaigns, set.steps),
+            merge_variable_warnings: mergeVariableWarnings,
             ...(contentWarnings.length ? { content_warnings: contentWarnings } : {}),
             next: approvalNext('activate_campaigns', approval),
         });

package/build/tools/campaigns.js

@@ -32,7 +32,7 @@ import { getScheduleWindowBounds, groupScheduleByCampaign, parseFutureDate } fro
 import { sendEmailForSite } from '../lib/email-provider.js';
 import { resolveSurveyShortLink } from '../lib/survey-link-resolver.js';
 import { logAudit } from '../audit.js';
-import { checkCampaignContent, contactPropertyKeys, eventKeysFromHistory, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
+import { checkCampaignMergeVariables, persistMergeVariableWarnings, summarizeMergeVariableWarnings, checkCampaignContent, contactPropertyKeys, eventKeysFromHistory, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
 import { recordBrandAssetUsage } from '../lib/brand-asset-usage.js';
 import { BLOCK_GENERATION_SCHEMA, blocksToHtml, blocksToText, normalizeComposerBlocks } from '../lib/composer-blocks.js';
 import { callSendinelV1 } from '../lib/v1-client.js';
@@ -1189,6 +1189,7 @@ export function registerCampaignTools(server) {
             approval_id: z.string().uuid().optional().describe('Required when activating. Get this by calling once without it, then have a human approve.'),
         },
     }, async ({ campaign_id, status, approval_id }) => {
+        let mergeVariableWarnings = [];
         // Human approval required for activation
         if (status === 'active') {
             // An imported email whose wait wasn't in the source has no delay; it would never send (#3689).
@@ -1227,10 +1228,11 @@ export function registerCampaignTools(server) {
                     .eq('campaign_id', campaign_id);
                 if (contentErr)
                     return j({ error: `Could not check the campaign's emails: ${dbToolError(contentErr).error}`, code: 'STEP_LOOKUP_FAILED' });
-                const readiness = await checkCampaignContent(getProjectId(), [campRow], contentSteps ?? []);
+                const readiness = await checkCampaignContent(getProjectId(), [campRow], contentSteps ?? [], { mergeVariables: false });
                 if (readiness.blocking.length)
                     return j(contentNotReadyResponse(readiness.blocking));
                 contentWarnings = contentWarningView(readiness.warnings, readiness.lookup_errors);
+                mergeVariableWarnings = await checkCampaignMergeVariables(getProjectId(), campRow, contentSteps ?? []);
             }
             const approvalParams = { campaign_id, status };
             if (!approval_id) {
@@ -1246,12 +1248,13 @@ export function registerCampaignTools(server) {
                         .eq('project_id', getProjectId())
                         .maybeSingle();
                     const approval = await requestApproval('update_campaign_status', approvalParams, undefined, channelContext, {
+                        merge_variable_summary: summarizeMergeVariableWarnings(mergeVariableWarnings),
                         campaign_name: camp?.name ?? null,
                         enrolled: typeof camp?.total_enrolled === 'number' ? camp.total_enrolled : null,
                         trigger: camp?.trigger_event_name ?? (camp?.trigger_tag ? `tag ${camp.trigger_tag}` : null),
                         ...(contentWarnings.length ? { content_warnings: summarizeContentWarnings(contentWarnings) } : {}),
                     });
-                    return j(contentWarnings.length ? { ...approval, content_warnings: contentWarnings } : approval);
+                    return j({ ...approval, merge_variable_warnings: mergeVariableWarnings, ...(contentWarnings.length ? { content_warnings: contentWarnings } : {}) });
                 }
             }
             else {
@@ -1269,6 +1272,11 @@ export function registerCampaignTools(server) {
             .single();
         if (error)
             return { content: [{ type: 'text', text: `Error: ${dbToolError(error).error}` }] };
+        if (status === 'active') {
+            await persistMergeVariableWarnings(getProjectId(), campaign_id, mergeVariableWarnings);
+            await logAudit({ action: 'campaign.status_changed', resourceType: 'campaign', resourceId: campaign_id,
+                details: { status, merge_variable_warnings: mergeVariableWarnings } }).catch(() => { });
+        }
         // Fire webhook for status changes
         const eventMap = { active: 'campaign.activated', completed: 'campaign.completed', paused: 'campaign.paused' };
         if (eventMap[status]) {
@@ -1278,7 +1286,7 @@ export function registerCampaignTools(server) {
                 status,
             }).catch(() => { });
         }
-        return { content: [{ type: 'text', text: JSON.stringify(campaignMetricsView(data), null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify({ ...campaignMetricsView(data), ...(status === 'active' ? { merge_variable_warnings: mergeVariableWarnings } : {}) }, null, 2) }] };
     });
     server.registerTool('enroll_contact', {
         title: 'Enroll Contact',
@@ -3411,6 +3419,7 @@ Return ONLY valid JSON with this exact shape:
         if (reentry.period_key !== undefined)
             targeting.period_key = reentry.period_key;
         const canActivateOnTrigger = campaignType === 'triggered' && (hasEventOrTag || targeting.trigger_type === 'date_field' || targeting.trigger_type === 'contact_event');
+        let mergeVariableWarnings = activate && !approval_id ? await checkCampaignMergeVariables(getProjectId(), { trigger_event_name: typeof targeting.trigger_event_name === 'string' ? targeting.trigger_event_name : null }, steps.map((step, step_order) => ({ ...step, step_order }))) : [];
         // Human-in-the-loop gate for activation
         if (activate && confirmed) {
             const approvalParams = { site_id, name, type, steps, segment_id, sends_per_hour, activate, send_class, unsub_footer_template, reentry_mode, period_key, ...triggerInput };
@@ -3421,8 +3430,8 @@ Return ONLY valid JSON with this exact shape:
             if (decision.tier !== 'autonomous') {
                 if (!approval_id) {
                     // No approval token — request one
-                    const approval = await requestApproval('create_campaign_with_content', approvalParams, undefined, channelContext);
-                    return j(approval);
+                    const approval = await requestApproval('create_campaign_with_content', approvalParams, undefined, channelContext, { merge_variable_summary: summarizeMergeVariableWarnings(mergeVariableWarnings) });
+                    return j({ ...approval, merge_variable_warnings: mergeVariableWarnings });
                 }
                 // Have a token — verify it's approved
                 const status = await checkApproval(approval_id, { consume: true, action: 'create_campaign_with_content', params: approvalParams });
@@ -3459,6 +3468,7 @@ Return ONLY valid JSON with this exact shape:
         if (!confirmed) {
             return j({
                 confirmation_required: true,
+                ...(activate ? { merge_variable_warnings: mergeVariableWarnings } : {}),
                 campaign: { name, type: campaignType, site: site.name, send_class: sendClass, unsub_footer_template: footerTemplate, ...targeting },
                 steps: steps.map((s, i) => ({
                     step: i + 1,
@@ -3559,6 +3569,8 @@ Return ONLY valid JSON with this exact shape:
         // 4. Activate if requested
         const willActivate = Boolean(activate && ((segment_id && enrolled > 0) || canActivateOnTrigger));
         if (willActivate) {
+            mergeVariableWarnings = await checkCampaignMergeVariables(getProjectId(), { trigger_event_name: typeof targeting.trigger_event_name === 'string' ? targeting.trigger_event_name : null }, stepInserts);
+            await persistMergeVariableWarnings(getProjectId(), campaign.id, mergeVariableWarnings);
             await db()
                 .from('campaigns')
                 .update({ status: 'active' })
@@ -3586,6 +3598,7 @@ Return ONLY valid JSON with this exact shape:
             steps_created: steps.length,
             contacts_enrolled: enrolled,
             status: willActivate ? 'active' : 'draft',
+            ...(willActivate ? { merge_variable_warnings: mergeVariableWarnings } : {}),
             message: `Campaign "${name}" created with ${steps.length} step(s). ${enrolled > 0 ? `${enrolled} contacts enrolled.` : 'No contacts enrolled.'} ${willActivate ? 'Campaign is now active — emails will begin sending on the next cron cycle.' : 'Campaign saved as draft.'}`,
         });
     });
@@ -4089,6 +4102,7 @@ Return ONLY valid JSON with this exact shape:
         const unresolvedCount = dlqUnresolvedCount ?? 0;
         return j({
             ...campaignMetricsView(campaign),
+            merge_variable_warnings: campaign.metadata?.merge_variable_warnings ?? [],
             reentry_mode: campaign.period_key ? "per_event_period" : "once_ever",
             requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION,
             ...await campaignTriggerOutput(campaign),

package/build/tools/contacts.js

@@ -1315,6 +1315,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             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.'),
+            is_test: z.boolean().optional().describe('Mark a NEW contact as a test contact: excluded from headline counts and default audiences. Ignored for existing contacts.'),
             source: z.enum(['signup', 'import', 'form', 'manual']).optional().default('manual'),
             utm_source: z.string().optional(),
             utm_medium: z.string().optional(),
@@ -1322,7 +1323,7 @@ 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, tags, 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, is_test, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
         try {
             const normalizedTags = normalizeTagInput(tags ?? []);
             const warnings = tagInputWarnings(normalizedTags);
@@ -1370,6 +1371,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 (is_test === true)
+                    row.is_test = true;
                 if (tags !== undefined)
                     row.tags = normalizedTags.tags;
                 if (customProperties)
@@ -1447,11 +1450,11 @@ 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, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}) });
+                await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}), ...(!existing && is_test === true ? { is_test: contact.is_test } : {}) });
                 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, ...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, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}) });
+            await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null, ...(!existing && tags !== undefined ? { tags: normalizedTags.tags } : {}), ...(!existing && is_test === true ? { is_test: contact.is_test } : {}) });
             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 } });

package/build/tools/gdpr.js

@@ -87,7 +87,7 @@ export function registerGdprTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'GDPR Article 17: Permanently delete a subscriber and all their data. Anonymizes email_log, hashes suppressions, cascades to subscriptions/enrollments/tokens. This action is IRREVERSIBLE. Requires human approval via dashboard.',
+        description: 'GDPR Article 17: Permanently delete a subscriber and all their data. Anonymizes email_log, hashes suppressions, cascades to subscriptions/enrollments/tokens. This action is IRREVERSIBLE. Also use for test contact cleanup (reason: admin). In a sandbox project, contacts created by the same credential are erased without a human click via the approval_id retry flow. Other cases require human approval via dashboard.',
         inputSchema: {
             contact_id: z.string().uuid().describe('UUID of the subscriber to delete'),
             reason: z.enum(['gdpr_request', 'user_request', 'admin']).optional().default('gdpr_request'),

package/build/tools/tool-search.js

@@ -12,6 +12,7 @@ export const STOPWORDS = new Set([
  * Only tools that exist in the registry belong here.
  */
 export const TOOL_ALIASES = {
+    delete_subscriber_data: ['delete contact', 'delete contacts', 'remove subscriber', 'remove subscribers', 'clean up test contacts', 'clean up test objects', 'sandbox cleanup'],
     list_custom_fields: ['custom fields', 'field definitions', 'contact schema', 'unused fields'],
     update_site: ['footer', 'email footer', 'unsubscribe text', 'unsubscribe link', 'site footer', 'unsubscribe settings'],
     set_campaign_trigger: ['trigger', 'event', 'fires on', 'fires-on', 'dunning', 'set campaign trigger event name', 'invoice payment failed', 'payment failed', 'trial ending', 'event trigger', 'billing'],

package/package.json

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