@sendinel/mcp-server 1.0.110 → 1.0.112

package/build/db.d.ts

@@ -32,6 +32,7 @@ export declare function setProjectClient(client: any): void;
  * @param fn     - Async function to run within this client's context.
  */
 export declare function runWithClient<T>(client: any, fn: () => Promise<T>, request?: {
+    scopes?: readonly string[];
     projectId?: string;
     approvalMode?: string;
     channel?: string;
@@ -48,12 +49,16 @@ export declare function runWithClient<T>(client: any, fn: () => Promise<T>, requ
     kid?: string | null;
     v1Caller?: V1Caller;
 }): Promise<T>;
-export declare function runWithToolContext<T>(toolGroup: string, toolName: string, fn: () => Promise<T> | T): Promise<T>;
+export declare function runWithToolContext<T>(toolGroup: string, toolName: string, fn: () => Promise<T> | T, scopes?: readonly string[] | null): Promise<T>;
+/** Keep the consumed-approval marker inside this async call; model input cannot set it. */
+export declare function runWithApprovedTesterRequest<T>(action: string, fn: () => Promise<T> | T): Promise<T>;
 /**
  * Request-scoped identity set via runWithClient() (HTTP transport).
  * Undefined under stdio, where the process env is the single-project source of truth.
  */
 export declare function requestContext(): {
+    scopes?: readonly string[];
+    approvedTesterAction?: string;
     projectId?: string;
     approvalMode?: string;
     channel?: string;

package/build/db.js

@@ -48,11 +48,18 @@ export async function runWithClient(
 client, fn, request) {
     return _requestStore.run({ client, ...request }, fn);
 }
-export async function runWithToolContext(toolGroup, toolName, fn) {
+export async function runWithToolContext(toolGroup, toolName, fn, scopes) {
     const current = _requestStore.getStore();
     if (!current)
-        return await _requestStore.run({ client: _processClient, toolGroup, toolName }, fn);
-    return await _requestStore.run({ ...current, toolGroup, toolName }, fn);
+        return await _requestStore.run({ client: _processClient, toolGroup, toolName, scopes: scopes ?? undefined }, fn);
+    return await _requestStore.run({ ...current, toolGroup, toolName, scopes: scopes ?? current.scopes }, fn);
+}
+/** Keep the consumed-approval marker inside this async call; model input cannot set it. */
+export async function runWithApprovedTesterRequest(action, fn) {
+    const current = _requestStore.getStore();
+    if (!current)
+        throw new Error('Tester application requires request context');
+    return _requestStore.run({ ...current, approvedTesterAction: action }, fn);
 }
 /**
  * Request-scoped identity set via runWithClient() (HTTP transport).
@@ -62,6 +69,8 @@ export function requestContext() {
     const ctx = _requestStore.getStore();
     return ctx
         ? {
+            scopes: ctx.scopes,
+            approvedTesterAction: ctx.approvedTesterAction,
             projectId: ctx.projectId,
             approvalMode: ctx.approvalMode,
             channel: ctx.channel,

package/build/lib/action-approvals.js

@@ -1,6 +1,9 @@
+import { isTesterRequest, isApplyingTesterRequest } from './tester-policy.js';
+import { logTesterRequestAudit } from './tester-request-audit.js';
+import { approvalStore } from './tester-requests-store.js';
 import { createHash } from 'node:crypto';
-import { buildApprovalPreview, isHumanApprovalChannel, triggerChangeSummary, decodeHtmlEntities, stripHtmlComments } from '@sendinel/domain';
-import { db, requestContext } from '../db.js';
+import { approvalSetupSummary, buildApprovalPreview, isHumanApprovalChannel, triggerChangeSummary, decodeHtmlEntities, stripHtmlComments } from '@sendinel/domain';
+import { requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
 import { captureApprovalSnapshot, withoutApprovalSnapshot } from './approval-snapshot.js';
 import { fireWebhookEvent } from './webhook-events.js';
@@ -97,6 +100,8 @@ export function isApprovalGatedAction(action) {
     return GATED_ACTIONS.has(action) || PROTECTED_ACTIONS.has(action);
 }
 export function getApprovalTier(action, params) {
+    if (isTesterRequest(action))
+        return isApplyingTesterRequest(action) ? 'autonomous' : 'gated';
     // CRITICAL: Protected actions ALWAYS require approval, even in autonomous mode.
     // These are irreversible (GDPR delete, merge, etc.) — no opt-out.
     if (PROTECTED_ACTIONS.has(action)) {
@@ -235,6 +240,9 @@ function launchSummary(p, d) {
 }
 /** Build a human-readable summary of the action for the approval screen */
 export function buildApprovalSummary(action, params, display = {}) {
+    const setup = approvalSetupSummary(action, params);
+    if (setup)
+        return setup;
     if ((action === 'update_campaign' || action === 'set_campaign_trigger') && params.previous_campaign && params.updates)
         return triggerChangeSummary(String(params.previous_campaign.name ?? params.campaign_id), params.previous_campaign, params.updates);
     const summaries = {
@@ -325,7 +333,6 @@ function approvalParamsEqual(expected, actual) {
  */
 export async function requestApproval(action, params, apiKeyId, channelContext, display) {
     const tier = getApprovalTier(action, params);
-    const summary = buildApprovalSummary(action, params, display);
     const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
     const { channel, verified } = channelContext ?? currentChannelContext();
     const actor = requestContext();
@@ -338,7 +345,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         throw new Error('Approval audience changed while preparing the preview. Request a new approval.');
     }
     const frozenParams = { ...cleanParams, __approval_snapshot: snapshot };
-    const { data, error } = await db()
+    const summary = buildApprovalSummary(action, frozenParams, display);
+    const { data, error } = await approvalStore()
         .from('action_approvals')
         .insert({
         project_id: getProjectId(),
@@ -358,6 +366,8 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         .single();
     if (error)
         throw new Error(`Failed to create approval request: ${error.message}`);
+    if (isTesterRequest(action))
+        await logTesterRequestAudit('tester_request', action, data.id, null);
     fireWebhookEvent('approval.requested', {
         approval_id: data.id,
         kind: action,
@@ -384,7 +394,7 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
  * Returns the approval if approved, null if still pending, throws if rejected/expired.
  */
 export async function checkApproval(approvalId, options = {}) {
-    const { data, error } = await db()
+    const { data, error } = await approvalStore()
         .from('action_approvals')
         .select('action, status, decided_by, decided_via, expires_at, used_at, params, payload_hash, requested_at')
         .eq('id', approvalId)
@@ -440,7 +450,7 @@ export async function checkApproval(approvalId, options = {}) {
     }
     if (expiry <= Date.now())
         return { approved: false, status: 'expired' };
-    const claimQuery = db()
+    const claimQuery = approvalStore()
         .from('action_approvals')
         .update({ status: 'used', used_at: new Date().toISOString() })
         .eq('id', approvalId)

package/build/lib/approval-elicitation.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { buildApprovalPreview, isHumanApprovalChannel } from '@sendinel/domain';
-import { db } from '../db.js';
+import { approvalStore } from './tester-requests-store.js';
 import { approvalAppClientAllowed, approvalClientName, approval_channel_available, probeApprovalCapabilities } from './approval-capabilities.js';
 // Keyed by the SDK Server, not the McpServer wrapper: other installers (the Apps tier) wrap
 // McpServer in a Proxy, which changes the wrapper's identity but never the connection's Server.
@@ -87,7 +87,7 @@ export async function elicitApproval(result, frozen, projectId) {
         // URL accept only means the page may open. Only its authenticated decision counts.
         // Observe while this request is alive; do not retain a background poller after timeout.
         while (!controller.signal.aborted) {
-            const source = db();
+            const source = approvalStore();
             const client = typeof source.schema === 'function' ? source.schema('email') : source;
             const { data, error } = await Promise.race([client.from('action_approvals')
                     .select('status, decided_via').eq('id', result.approval_id).eq('project_id', projectId).maybeSingle(), stopped]);

package/build/lib/approval-human-callback.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { db } from '../db.js';
+import { approvalStore } from './tester-requests-store.js';
 /**
  * Server integration only. The transport creates this closure for one authenticated human
  * interaction and retains it outside the tool registry. Neither its id nor decision is a tool
@@ -16,7 +16,7 @@ export function createHumanApprovalCallback(binding) {
             if (response.decision !== 'approve' && response.decision !== 'reject')
                 return false;
             completed = true;
-            const source = db();
+            const source = approvalStore();
             const client = typeof source.schema === 'function' ? source.schema('email') : source;
             const now = new Date().toISOString();
             const { data, error } = await client.from('action_approvals')

package/build/lib/approval-snapshot.js

@@ -1,3 +1,5 @@
+import { isTesterRequest } from './tester-policy.js';
+import { captureTesterRequestSnapshot } from './tester-request-snapshot.js';
 import { readAllRows, chunkIds, scopeSegmentRulesToSite } from '@sendinel/domain';
 import { db } from '../db.js';
 import { resolveSendAudience, resolveSegmentContactIds } from './send-audience.js';
@@ -6,9 +8,10 @@ const TARGET_ACTIONS = new Set(['send_broadcast', 'broadcast_to_segment', 'launc
     'send_transactional', 'send_awaiting_reply', 'send_test_email', 'send_newsletter_issue', 'schedule_newsletter_issue']);
 /** Server-owned display facts, saved inside the hash-bound params. Never supplied by a tool. */
 export async function captureApprovalSnapshot(action, params, projectId) {
+    const setup = isTesterRequest(action) ? await captureTesterRequestSnapshot(action, params, projectId) : null;
     const snapshot = { version: 1, campaigns: [], steps: [], sites: [], recipient_count: null };
     if (!TARGET_ACTIONS.has(action))
-        return snapshot;
+        return setup ?? snapshot;
     const source = db();
     const client = typeof source.schema === 'function' ? source.schema('email') : source;
     const body = params.payload ?? params;
@@ -98,7 +101,7 @@ export async function captureApprovalSnapshot(action, params, projectId) {
     }
     snapshot.campaigns.sort((a, b) => String(a.id).localeCompare(String(b.id)));
     snapshot.steps.sort((a, b) => String(a.id).localeCompare(String(b.id)));
-    return snapshot;
+    return setup ? { ...snapshot, ...setup, recipient_count: snapshot.recipient_count, audience_snapshot: snapshot } : snapshot;
 }
 export function withoutApprovalSnapshot(params) {
     const { __approval_snapshot: _snapshot, ...rest } = (params ?? {});

package/build/lib/campaign-trigger-approval.js

@@ -1,3 +1,4 @@
+import { isApplyingTesterRequest } from './tester-policy.js';
 import { isDeepStrictEqual } from 'node:util';
 import { campaignTriggerChanges, campaignTriggerRevision, triggerChangeNeedsApproval } from '@sendinel/domain';
 import { db } from '../db.js';
@@ -22,7 +23,7 @@ export async function finishCampaignEdit(action, input, existing, updates, reque
     if (campaignTriggerChanges(existing, updates) && !['draft', 'active', 'paused'].includes(existing.status)) {
         return campaignEditError(`Cannot change a ${existing.status} campaign trigger`, 'INVALID_STATUS');
     }
-    if (!triggerChangeNeedsApproval(existing, updates))
+    if (isApplyingTesterRequest(action) || !triggerChangeNeedsApproval(existing, updates))
         return writeEdit(input.campaign_id, existing, updates);
     const params = { campaign_id: input.campaign_id, input, previous_campaign: existing, updates };
     const context = currentChannelContext();

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

@@ -3,9 +3,28 @@ import { rankTools, scoreTool, tokenize, TOOL_ALIASES } from '../tools/tool-sear
 const approval = { required: true, how: 'returns approve_url; re-call with approval_id' };
 const from = (n, field) => `<from step ${n}: ${field}>`;
 const projectRule = 'On hosted /mcp, pass project_id on each call. It is required for approval-gated writes after switching away from the home project. With invoke_tool put project_id on the outer call; keep approval-only inner args to approval_id.';
-const previewRule = 'preview_email only substitutes sample merge variables; it is not the real send renderer. send_test_email with dry_run:true uses the real renderer without sending, but still follows the approval flow in standard mode; keep the same args plus approval_id when re-calling it. Stdio requires SENDINEL_API_KEY.';
+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, but still follows the approval flow in standard mode; keep the same args plus approval_id when re-calling it. 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: 'event-driven-billing-mail-end-to-end', title: 'Event-driven billing mail end to end',
+        when_to_use: 'Build and verify event-driven billing, dunning, payment failed or trial ending transactional mail, then request human approval for activation.',
+        synonyms: ['event-driven billing mail end to end', 'billing', 'dunning', 'trial ending', 'transactional', 'payment failed'],
+        requires: { scopes: ['admin'], tester_ok: false },
+        steps: [sender,
+            { n: 2, tool: 'create_campaign_with_content', args_example: { site_id: from(1, '0.id'), name: 'Payment failed', type: 'triggered', trigger_event_name: 'invoice_payment_failed', send_class: 'product', steps: [{ subject: 'Please update your payment method', body_html: '<p>Please sign in to review your payment method.</p>', body_text: 'Please sign in to review your payment method.', delay_days: 0 }], activate: false, confirmed: false }, note: 'Preview the draft creation. Replace the event and content with the actual integration event and reviewed copy. product is the account/trial/billing consent class; transactional is not an enum value.' },
+            { n: 3, tool: 'create_campaign_with_content', args_example: { site_id: from(1, '0.id'), name: 'Payment failed', type: 'triggered', trigger_event_name: 'invoice_payment_failed', send_class: 'product', steps: [{ subject: 'Please update your payment method', body_html: '<p>Please sign in to review your payment method.</p>', body_text: 'Please sign in to review your payment method.', delay_days: 0 }], activate: false, confirmed: true }, note: 'Repeat the reviewed creation args with confirmed:true. Keep activate:false; no segment is required. Follow any returned setup approval before execution.' },
+            { n: 4, tool: 'set_campaign_trigger', args_example: { campaign_id: from(3, 'campaign_id'), trigger_event_name: 'invoice_payment_failed', trigger_config: { events: ['invoice_payment_failed'], where: { plan: 'paid' } } }, approval, note: 'Use event-data keys actually emitted by the integration. Drafts save directly; if approval is requested, wait for the human and follow the returned re-call instructions. trial_ending and trial_ending_no_card are alternative event names.' },
+            { n: 5, tool: 'update_site', args_example: { site_id: from(1, '0.id'), unsub_footer_template: "You're receiving this because you have an account. <unsubscribe>Unsubscribe</unsubscribe>" }, note: 'Site-wide change: review its effect on every campaign using this sender, keep previous_unsub_footer_template for undo, and follow any returned approval. Leave physical_address unchanged. For only this campaign, skip this call and instead pass unsub_footer_template with this same tagged text to BOTH creation calls; a null campaign override uses the site template.' },
+            { n: 6, tool: 'list_campaign_steps', args_example: { campaign_id: from(3, 'campaign_id') }, note: 'Choose the intended saved step; preview each step in a multi-step sequence.' },
+            { n: 7, tool: 'preview_email', args_example: { step_id: from(6, 'steps.0.id') }, note: 'Check the rendered footer (campaign override else site), unsubscribe scope for product, sender and physical address. Sample placeholder links are not delivery proof.' },
+            { n: 8, tool: 'activate_campaigns', args_example: { campaign_ids: [from(3, 'campaign_id')] }, approval, note: 'Human approval is required. Show the exact content, sender, event/filter and approve_url. Stop until a human approves; never approve on their behalf.' },
+            { n: 9, tool: 'activate_campaigns', args_example: { approval_id: from(8, 'approval_id') }, approval, note: 'Only after human approval, re-call with ONLY approval_id. This activates the saved campaign and can cause future matching events to send mail.' },
+            { n: 10, tool: 'get_campaign', args_example: { campaign_id: from(3, 'campaign_id') }, note: 'Final read back: verify fires_on, trigger_diagnostics, status, send_class, unsub_footer_template and the saved trigger_config.where.' },
+        ],
+        gotchas: [projectRule, previewRule, 'Never activate without human approval. A trigger binding does not emit an event or enroll historical events. Product mail still follows consent/suppression gates; preview does not prove eligibility or delivery. Setup writes may require their own approval depending on the connection role.'],
+        done_when: 'The reviewed draft renders the intended footer and product scope, activation has human approval, and get_campaign confirms fires_on and trigger_diagnostics. Real delivery remains unverified until a separately authorized event test.',
+    },
     {
         id: 'set-campaign-trigger', title: 'Set what a campaign fires on',
         when_to_use: 'Bind an existing campaign to an event such as invoice_payment_failed for dunning, or change its tag/date/contact-event trigger.',
@@ -23,7 +42,7 @@ export const HOW_TO_RECIPES = [
         id: 'send-one-off-email', title: 'Send a one-off email to my list',
         when_to_use: 'Send an announcement or email blast to an audience with human approval.',
         synonyms: TOOL_ALIASES.send_broadcast,
-        requires: { scopes: ['write'], tester_ok: true },
+        requires: { scopes: ['write'], tester_ok: false },
         steps: [
             { n: 1, tool: 'send_broadcast', args_example: { audience: 'subscribers to the intended sender', subject: 'A quick update', html: '<p>Here is the update you requested.</p>' }, approval, note: 'Specify site_id if there is more than one sender. Show the subject, recipient_count, sender, finished email and approve_url; wait for a person to approve.' },
             { n: 2, tool: 'send_broadcast', args_example: { approval_id: from(1, 'approval_id') }, approval, note: 'Only after human approval. Pass ONLY approval_id; changed content needs a new request.' },

package/build/lib/tester-policy.d.ts

@@ -0,0 +1,6 @@
+/** Campaign setup only. Never infer this permission from a prefix or model arguments. */
+export declare const TESTER_REQUEST_TOOLS: ReadonlySet<string>;
+export declare const TESTER_SITE_FIELDS: ReadonlySet<string>;
+export declare function isTesterRequest(action: string): boolean;
+/** Server-only context set after the shared core has consumed a human-approved payload. */
+export declare function isApplyingTesterRequest(action: string): boolean;

package/build/lib/tester-policy.js

@@ -0,0 +1,18 @@
+import { requestContext } from '../db.js';
+/** Campaign setup only. Never infer this permission from a prefix or model arguments. */
+export const TESTER_REQUEST_TOOLS = new Set([
+    'update_site', 'update_campaign', 'set_campaign_trigger', 'create_campaign',
+    'create_campaign_with_content', 'add_campaign_step', 'update_campaign_step',
+]);
+export const TESTER_SITE_FIELDS = new Set([
+    'unsub_link_enabled', 'unsub_one_click_enabled', 'unsub_custom_url',
+    'unsub_footer_template', 'unsub_custom_message', 'unsub_brand_logo_url', 'unsub_brand_color',
+]);
+export function isTesterRequest(action) {
+    const ctx = requestContext();
+    return !!ctx?.scopes?.includes('tester') && !ctx.scopes.includes('agent') && TESTER_REQUEST_TOOLS.has(action);
+}
+/** Server-only context set after the shared core has consumed a human-approved payload. */
+export function isApplyingTesterRequest(action) {
+    return isTesterRequest(action) && requestContext()?.approvedTesterAction === action;
+}

package/build/lib/tester-request-audit.d.ts

@@ -0,0 +1,2 @@
+/** Central audit infrastructure, including when the edited site belongs to a BYOD project. */
+export declare function logTesterRequestAudit(event: 'tester_request' | 'tester_applied', action: string, approvalId: string, approver: string | null): Promise<void>;

package/build/lib/tester-request-audit.js

@@ -0,0 +1,15 @@
+import { requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { approvalStore } from './tester-requests-store.js';
+/** Central audit infrastructure, including when the edited site belongs to a BYOD project. */
+export async function logTesterRequestAudit(event, action, approvalId, approver) {
+    const ctx = requestContext();
+    const { error } = await approvalStore().from('audit_log').insert({
+        project_id: getProjectId(), actor_type: ctx?.actorType ?? 'mcp', actor_id: ctx?.actorId ?? null,
+        action: `mcp_connection.${event}`, resource_type: 'mcp_connection', resource_id: ctx?.oauthTokenId,
+        channel: ctx?.channel ?? 'mcp',
+        details: { connection_id: ctx?.oauthTokenId, approval_id: approvalId, tool: action, approver },
+    });
+    if (error)
+        throw new Error(`Failed to audit tester ${event}: ${error.message}`);
+}

package/build/lib/tester-request-snapshot.d.ts

@@ -0,0 +1,4 @@
+type Row = Record<string, any>;
+/** Setup targets and before values, frozen by the same hash and revalidation as sending approvals. */
+export declare function captureTesterRequestSnapshot(action: string, params: Row, projectId: string): Promise<Row>;
+export {};

package/build/lib/tester-request-snapshot.js

@@ -0,0 +1,46 @@
+import { readAllRows } from '@sendinel/domain';
+import { db, requestContext } from '../db.js';
+/** Setup targets and before values, frozen by the same hash and revalidation as sending approvals. */
+export async function captureTesterRequestSnapshot(action, params, projectId) {
+    const source = db();
+    const client = typeof source.schema === 'function' ? source.schema('email') : source;
+    const snapshot = { version: 1, tester_connection_id: requestContext()?.oauthTokenId,
+        campaigns: [], steps: [], sites: [], recipient_count: null };
+    let campaignId = params.campaign_id;
+    if (action === 'update_campaign_step') {
+        const { data, error } = await client.from('campaign_steps').select('*').eq('id', params.step_id).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval step unavailable');
+        campaignId = data.campaign_id;
+    }
+    if (campaignId) {
+        const { data, error } = await client.from('campaigns')
+            .select('id, name, description, site_id, segment_id, type, status, topic, send_at, sends_per_hour, send_in_contact_timezone, send_class, requires_approval, unsub_footer_template, trigger_type, trigger_event_name, trigger_tag, trigger_config, updated_at')
+            .eq('id', campaignId).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval campaign unavailable');
+        snapshot.campaigns = [data];
+        snapshot.steps = await readAllRows(client.from('campaign_steps').select('*').eq('campaign_id', campaignId));
+        snapshot.steps.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+        if (params.step_id && !snapshot.steps.some((step) => step.id === params.step_id))
+            throw new Error('Approval step unavailable');
+    }
+    const siteIds = [...new Set([params.site_id, ...snapshot.campaigns.map((campaign) => campaign.site_id)]
+            .filter((id) => typeof id === 'string'))].sort();
+    for (const siteId of siteIds) {
+        const { data, error } = await client.from('sites')
+            .select('id, name, from_name, from_email, sending_domain, physical_address, unsub_link_enabled, unsub_one_click_enabled, unsub_custom_url, unsub_footer_template, unsub_custom_message, unsub_brand_logo_url, unsub_brand_color, updated_at')
+            .eq('id', siteId).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval site unavailable');
+        snapshot.sites.push(data);
+    }
+    if (params.segment_id) {
+        const { data, error } = await client.from('segments').select('id, name, rules, site_id')
+            .eq('id', params.segment_id).eq('project_id', projectId).maybeSingle();
+        if (error || !data)
+            throw new Error('Approval segment unavailable');
+        snapshot.segment = data;
+    }
+    return snapshot;
+}

package/build/lib/tester-requests-store.d.ts

@@ -0,0 +1,2 @@
+/** Approval infrastructure stays central, including when update_site uses a BYOD client. */
+export declare function approvalStore(): any;

package/build/lib/tester-requests-store.js

@@ -0,0 +1,8 @@
+import { adminDb, db, requestContext } from '../db.js';
+/** Approval infrastructure stays central, including when update_site uses a BYOD client. */
+export function approvalStore() {
+    if (!requestContext()?.scopes?.includes('tester'))
+        return db();
+    const source = adminDb();
+    return typeof source.schema === 'function' ? source.schema('email') : source;
+}

package/build/lib/tester-requests.d.ts

@@ -0,0 +1,5 @@
+/** Only installed for an authenticated tester connection, never selected by tool arguments. */
+export declare function testerRequestTool(action: string, config: any, handler: (...args: any[]) => any): {
+    config: any;
+    handler: (input: Record<string, unknown>, extra?: unknown) => Promise<any>;
+};

package/build/lib/tester-requests.js

@@ -0,0 +1,71 @@
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { requestContext, runWithApprovedTesterRequest } from '../db.js';
+import { getProjectId } from '../project.js';
+import { withApproval } from './action-approvals.js';
+import { withoutApprovalSnapshot } from './approval-snapshot.js';
+import { approvalStore } from './tester-requests-store.js';
+import { logTesterRequestAudit } from './tester-request-audit.js';
+import { TESTER_SITE_FIELDS } from './tester-policy.js';
+const text = (message) => ({ content: [{ type: 'text', text: message }] });
+/** Only installed for an authenticated tester connection, never selected by tool arguments. */
+export function testerRequestTool(action, config, handler) {
+    const original = z.object(config.inputSchema);
+    // Wrapping before optional prevents Zod defaults from populating an approval-id-only retry.
+    const inputSchema = Object.fromEntries(Object.entries(config.inputSchema).map(([key, schema]) => [key, z.preprocess(value => value, schema).optional()]));
+    inputSchema.approval_id = z.string().uuid().optional();
+    return {
+        config: { ...config, inputSchema },
+        handler: async (input, extra) => {
+            if (!requestContext()?.oauthTokenId)
+                return text('Tester setup requires an authenticated connection id.');
+            const { approval_id, ...supplied } = input;
+            let params;
+            if (approval_id) {
+                const { data, error } = await approvalStore().from('action_approvals').select('*')
+                    .eq('id', approval_id).eq('project_id', getProjectId()).maybeSingle();
+                if (error || !data || data.action !== action || data.oauth_token_id !== requestContext()?.oauthTokenId) {
+                    return text('Approval not found for this action and tester connection.');
+                }
+                params = withoutApprovalSnapshot(data.params);
+                for (const [key, value] of Object.entries(supplied)) {
+                    if (value !== undefined && !isDeepStrictEqual(value, params[key]))
+                        return text('params_mismatch: request differs from the frozen payload.');
+                }
+            }
+            else {
+                const parsed = original.safeParse(supplied);
+                if (!parsed.success)
+                    return text(`Invalid request: ${parsed.error.message}`);
+                params = parsed.data;
+                delete params.approval_id;
+                // This human approval replaces the compound tool's model confirmation preview.
+                if (action === 'create_campaign_with_content')
+                    params.confirmed = true;
+            }
+            if (action === 'update_site' && Object.keys(params).some(key => key !== 'site_id' && params[key] !== undefined && !TESTER_SITE_FIELDS.has(key))) {
+                return text('Tester connections may request only site footer and unsubscribe settings.');
+            }
+            return withApproval(action, async (frozen) => {
+                const result = await runWithApprovedTesterRequest(action, () => handler(frozen, extra));
+                // All seven setup tools report a successful apply as a resource id or an explicit ok.
+                let value;
+                try {
+                    value = JSON.parse(result.content.filter((block) => block.type === 'text')
+                        .map((block) => block.text).join('\n'));
+                }
+                catch {
+                    return result;
+                }
+                if (!result.isError && !value.error && (value.id || value.campaign_id || value.ok === true)) {
+                    const { data, error } = await approvalStore().from('action_approvals').select('decided_by')
+                        .eq('id', approval_id).eq('project_id', getProjectId()).maybeSingle();
+                    if (error || !data?.decided_by)
+                        throw new Error('Applied tester request has no recorded approver');
+                    await logTesterRequestAudit('tester_applied', action, String(approval_id), data.decided_by);
+                }
+                return result;
+            })({ ...params, approval_id: approval_id }, extra);
+        },
+    };
+}

package/build/server.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { TESTER_REQUEST_TOOLS } from './lib/tester-policy.js';
 export interface ToolRegistrationOptions {
     scopes?: string[];
     toolGroups?: string[];
@@ -19,7 +20,7 @@ export declare function isAgentConnection(scopes: readonly string[] | null | und
 export declare function agentConnectionAllowsTool(name: string): boolean;
 export declare function agentConnectionRefusal(name: string): string;
 export declare function isTesterConnection(scopes: readonly string[] | null | undefined): boolean;
-/** Tools a tester connection may see and call: reads, plus anything that goes through a person's approval. */
+/** Tester reads, explicit setup requests and the existing campaign activation paths. */
 export declare function testerConnectionAllowsTool(name: string): boolean;
 /**
  * Tools whose own input already has a top-level `project_id` that means something other than "the project
@@ -31,7 +32,7 @@ export declare const PROJECT_ID_NATIVE_TOOLS: ReadonlySet<string>;
  * Tools that need a stated project when the connection is switched away from its home project (#4033):
  * anything that goes through a person's approval, plus the two always-gated actions.
  */
-export declare function isProjectPinnedWriteTool(name: string): boolean;
+export declare function isProjectPinnedWriteTool(name: string, scopes?: readonly string[]): boolean;
 export declare function testerConnectionRefusal(name: string): string;
 export declare const GATEWAY_TOOL_NAMES: string[];
 /**
@@ -46,4 +47,3 @@ export declare function getRegisteredToolGroups(options?: ToolRegistrationOption
  */
 export declare const SENDINEL_SERVER_INSTRUCTIONS: string;
 export declare function registerAllTools(server: McpServer, options?: ToolRegistrationOptions): void;
-export {};

package/build/server.js

@@ -2,6 +2,9 @@ import { installApprovalCapabilityProbe } from './lib/approval-capabilities.js';
 import { installApprovalApp } from './lib/approval-app.js';
 import { runWithApprovalElicitation } from './lib/approval-elicitation.js';
 import { runWithToolContext } from './db.js';
+import { TESTER_REQUEST_TOOLS } from './lib/tester-policy.js';
+import { testerRequestTool } from './lib/tester-requests.js';
+export { TESTER_REQUEST_TOOLS } from './lib/tester-policy.js';
 import { isApprovalGatedAction } from './lib/action-approvals.js';
 import { registerAgentMailboxTools } from './tools/agent-mailboxes.js';
 import { registerAnalyticsTools } from './tools/analytics.js';
@@ -203,14 +206,14 @@ export function agentConnectionRefusal(name) {
 export function isTesterConnection(scopes) {
     return !!scopes?.includes(TESTER_CONNECTION_SCOPE);
 }
-/** Tools a tester connection may see and call: reads, plus anything that goes through a person's approval. */
+/** Tester reads, explicit setup requests and the existing campaign activation paths. */
 export function testerConnectionAllowsTool(name) {
-    if (name === 'create_agent_mailbox')
-        return false;
+    // Retain the existing campaign activation path. A globally gated tool is not by itself
+    // permission for a tester: sends, deletes and access/infrastructure writes stay refused.
     return getRequiredScope(name) === 'read'
-        || name === 'send_broadcast'
+        || TESTER_REQUEST_TOOLS.has(name)
         || name === 'activate_campaigns'
-        || isApprovalGatedAction(name);
+        || name === 'update_campaign_status';
 }
 /**
  * Tools whose own input already has a top-level `project_id` that means something other than "the project
@@ -222,11 +225,11 @@ export const PROJECT_ID_NATIVE_TOOLS = new Set(['set_active_project', 'get_outbo
  * Tools that need a stated project when the connection is switched away from its home project (#4033):
  * anything that goes through a person's approval, plus the two always-gated actions.
  */
-export function isProjectPinnedWriteTool(name) {
-    return name === 'send_broadcast' || name === 'activate_campaigns' || isApprovalGatedAction(name);
+export function isProjectPinnedWriteTool(name, scopes) {
+    return (isTesterConnection(scopes) && TESTER_REQUEST_TOOLS.has(name)) || name === 'send_broadcast' || name === 'activate_campaigns' || isApprovalGatedAction(name);
 }
 export function testerConnectionRefusal(name) {
-    return `"${name}" is not available to a tester connection. A tester connection can read, and can ask a person to approve outward actions: call an approval-gated tool (for example send_broadcast) and a person approves it from the approve_url it returns. To change this tool directly, ask the workspace owner to promote the connection in Dashboard > Agent Connect.`;
+    return `"${name}" is not available to a tester connection. Testers can read and request human approval for campaign setup: ${[...TESTER_REQUEST_TOOLS].join(', ')}. update_site is limited to footer/unsubscribe fields. Every setup call returns approval_id, approve_url and preview_text; after a person approves, retry with only approval_id. Deletes, sends, access/role/key/team tools, provider credentials, imports and create_agent_mailbox are refused. Ask the workspace owner to promote the connection in Dashboard > Agent Connect for direct writes.`;
 }
 // Names of the meta-tools gateway mode registers in place of the real catalog
 // (see tools/gateway.ts). Grouped as 'gateway' rather than any real tool
@@ -350,13 +353,18 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                             // Don't register tools the key can't access — they won't appear in tool list
                             return;
                         }
+                        if (tester && !agent && TESTER_REQUEST_TOOLS.has(name)) {
+                            const wrapped = testerRequestTool(name, config, handler);
+                            config = wrapped.config;
+                            handler = wrapped.handler;
+                        }
                         // Wrap handler with runtime scope check (defense in depth)
                         const guardedHandler = (...args) => {
                             if (!allowed()) {
                                 const text = agent ? agentConnectionRefusal(name) : tester ? testerConnectionRefusal(name) : `Forbidden: this action requires "${required}" scope.`;
                                 return { content: [{ type: 'text', text }] };
                             }
-                            return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)));
+                            return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)), scopes);
                         };
                         return target.registerTool(name, config, guardedHandler);
                     }

package/build/tools/campaigns.js

@@ -2279,17 +2279,18 @@ Do not include body_html in your response; Sendinel renders body_html from block
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Preview email through the real send renderer using sample contact data; unresolved_tags lists remaining tags. Provide content via step_id, draft_id, or raw body_html/subject.',
+        description: 'Preview email through the real send renderer: final campaign/site footer, unsubscribe text and send_class scope, sender and physical address. Uses sample contact data; unresolved_tags lists remaining tags. Provide campaign_id, step_id, draft_id, or raw body_html/subject.',
         inputSchema: {
             site_id: z.string().uuid().optional().describe('Site UUID for sender tags and footers'),
+            campaign_id: z.string().uuid().optional().describe('Campaign UUID; previews its first step in send order. Use step_id to choose a specific step.'),
             step_id: z.string().uuid().optional().describe('Campaign step UUID'),
             draft_id: z.string().uuid().optional().describe('AI draft UUID'),
             subject: z.string().optional().describe('Raw subject'),
             body_html: z.string().optional().describe('Raw HTML'),
         },
-    }, async ({ step_id, draft_id, subject, body_html, site_id }) => {
+    }, async ({ campaign_id, step_id, draft_id, subject, body_html, site_id }) => {
         const result = await callSendinelV1('/api/v1/campaigns/preview', {
-            body: { step_id, draft_id, subject, body_html, site_id },
+            body: { campaign_id, step_id, draft_id, subject, body_html, site_id },
         });
         return result.ok ? j(result.data) : j({ error: result.error, status: result.status });
     });
@@ -2961,7 +2962,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: false,
             openWorldHint: true,
         },
-        description: 'Create a sequence, broadcast or triggered campaign with pre-built email content in one call. Set trigger_event_name for dunning (invoice_payment_failed, trial_ending), trigger_tag, or date_field/contact_event trigger_config; events/tags and where filters are supported. Triggered campaigns need no segment. Returns fires_on and trigger_diagnostics. Adds email steps, optionally enrolls a segment, and activates behind standard approval. Ideal for orchestrators that draft their own content — skips AI generation. Uses two-call confirmation: first call returns a preview, second call with confirmed=true executes.',
+        description: 'Create billing, dunning, trial ending or transactional mail with send_class=product (broadcast is the marketing default). Build a sequence, broadcast or triggered campaign with pre-built steps. Override unsubscribe text with unsub_footer_template. Set trigger_event_name for dunning (invoice_payment_failed, trial_ending), trigger_tag, or date_field/contact_event trigger_config; events/tags and where filters are supported. Triggered campaigns need no segment. Returns fires_on and trigger_diagnostics. Adds email steps, optionally enrolls a segment, and activates behind standard approval. Ideal for orchestrators that draft their own content — skips AI generation. Uses two-call confirmation: first call returns a preview, second call with confirmed=true executes.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site to send from'),
             name: z.string().min(1).max(200).describe('Campaign name'),
@@ -3357,7 +3358,7 @@ Return ONLY valid JSON with this exact shape:
     server.registerTool('set_campaign_trigger', {
         title: 'Set Campaign Trigger',
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-        description: 'Set or clear what a campaign fires on: trigger event name, tag, date_field, contact_event, or trigger_config events/tags and where event-data filter. Use for dunning on invoice_payment_failed or trial_ending. Drafts save directly; active/paused campaigns require standard human approval. Archived/completed campaigns cannot change. Returns saved trigger fields, fires_on and trigger_diagnostics.',
+        description: 'Set or clear what a campaign fires on: trigger event name, tag, date_field, contact_event, or trigger_config events/tags and where event-data filter. Bind billing, payment failed, dunning or trial ending mail to an event trigger such as invoice_payment_failed or trial_ending. Drafts save directly; active/paused campaigns require standard human approval. Archived/completed campaigns cannot change. Returns saved trigger fields, fires_on and trigger_diagnostics.',
         inputSchema: {
             campaign_id: z.string().uuid().optional(),
             trigger_event_name: z.string().nullable().optional(),

package/build/tools/tool-search.js

@@ -13,7 +13,9 @@ export const STOPWORDS = new Set([
  */
 export const TOOL_ALIASES = {
     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', 'trial ending'],
+    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'],
+    create_campaign_with_content: ['billing', 'dunning', 'trial ending', 'transactional', 'payment failed', 'product email', 'event-driven billing mail'],
+    preview_email: ['preview footer', 'footer', 'unsubscribe text', 'preview billing email', 'unsubscribe scope'],
     send_broadcast: [
         'send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email',
         'email my list', 'send to my list', 'email to my list', 'email my subscribers',

package/package.json

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