@sendinel/mcp-server 1.0.139 → 1.0.141

package/build/lib/db-error.d.ts

@@ -0,0 +1,16 @@
+/** Public tool errors must not expose SQL, constraint names or database internals. */
+export declare function dbToolError(error: {
+    code?: string;
+    message?: string;
+}, message?: string): {
+    error: string;
+    code: string;
+};
+/** Mark coded failures as MCP errors so the hosted api_usage classifier sees them. */
+export declare function toolError(body: unknown): {
+    isError: true;
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};

package/build/lib/db-error.js

@@ -0,0 +1,17 @@
+/** Public tool errors must not expose SQL, constraint names or database internals. */
+export function dbToolError(error, message = 'Unable to complete database operation') {
+    if (error.code === '23505')
+        return { error: 'A record with these values already exists', code: 'conflict' };
+    if (error.code === '23503')
+        return { error: 'Referenced record not found', code: 'not_found' };
+    if (error.code === '42501')
+        return { error: 'Operation forbidden', code: 'forbidden' };
+    if (error.code?.startsWith('22') || error.code === '23514' || error.code === '23502') {
+        return { error: 'Invalid record values', code: 'validation_failed' };
+    }
+    return { error: message, code: 'internal_error' };
+}
+/** Mark coded failures as MCP errors so the hosted api_usage classifier sees them. */
+export function toolError(body) {
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+}

package/build/lib/db-errors.d.ts

@@ -0,0 +1,12 @@
+/** Caller-safe database errors. Never serialize database messages, details or hints. */
+export declare function mapDbError(error: unknown): {
+    error: string;
+    code: string;
+};
+export declare function dbErrorResult(error: unknown): {
+    isError: boolean;
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};

package/build/lib/db-errors.js

@@ -0,0 +1,20 @@
+/** Caller-safe database errors. Never serialize database messages, details or hints. */
+export function mapDbError(error) {
+    const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+    if (code === '23505')
+        return { error: 'A record with these values already exists.', code: 'conflict' };
+    if (code === '23503' || code === 'PGRST116') {
+        return { error: 'The requested or referenced record was not found.', code: 'not_found' };
+    }
+    if (code.startsWith('23') || code.startsWith('22')) {
+        return { error: 'The supplied values are not valid. Check the input and try again.', code: 'validation_failed' };
+    }
+    return { error: 'The operation could not be completed. Please try again later.', code: 'internal_error' };
+}
+export function dbErrorResult(error) {
+    console.warn('[mcp] Database operation failed:', error);
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(mapDbError(error)) }],
+    };
+}

package/build/tools/advisor.js

@@ -1,8 +1,9 @@
-import { countEmailRows, groupMetricRows, percentRate, isDeliveredRow, isOpenedRow, countPeople, isComplainedRow, isBouncedRow, AI_MAX_TOKENS, outputConfig, anthropicCheckedText, readAllRows } from "@sendinel/domain";
+import { countEmailRows, groupMetricRows, percentRate, isBouncedRow, AI_MAX_TOKENS, outputConfig, anthropicCheckedText, readAllRows } from "@sendinel/domain";
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
+import { toolError } from '../lib/db-error.js';
 import { buildVoicePrompt } from '../lib/voice.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { dkimRemediationText } from '../lib/email-provider.js';
@@ -103,19 +104,19 @@ export function registerAdvisorTools(server) {
         // 1. Current period email_log
         let currentQuery = db()
             .from('email_log')
-            .select("status, created_at, bounced_at, opened_at, clicked_at, contact_id, to_email")
+            .select("status, sent_at, bounced_at, opened_at, clicked_at, contact_id, to_email")
             .eq('project_id', projectId)
-            .gte('created_at', periodStart.toISOString());
+            .gte('sent_at', periodStart.toISOString());
         if (site_id)
             currentQuery = currentQuery.eq('site_id', site_id);
         const currentRows = await readAllRows(currentQuery);
         // 2. Prior period
         let priorQuery = db()
             .from('email_log')
-            .select("status, created_at, bounced_at, opened_at, clicked_at, contact_id, to_email")
+            .select("status, sent_at, bounced_at, opened_at, clicked_at, contact_id, to_email")
             .eq('project_id', projectId)
-            .gte('created_at', priorStart.toISOString())
-            .lt('created_at', periodStart.toISOString());
+            .gte('sent_at', priorStart.toISOString())
+            .lt('sent_at', periodStart.toISOString());
         if (site_id)
             priorQuery = priorQuery.eq('site_id', site_id);
         const priorRows = await readAllRows(priorQuery);
@@ -124,8 +125,8 @@ export function registerAdvisorTools(server) {
         // 3. Domain health (latest per site)
         let healthQuery = db()
             .from('domain_health')
-            .select('site_id, bounce_rate, complaint_rate, spf_valid, dkim_valid, dmarc_valid, warmup_day')
-            .eq('project_id', projectId)
+            .select('site_id, bounce_rate, complaint_rate, spf_valid, dkim_valid, dmarc_valid, warmup_day, sites!inner(project_id)')
+            .eq('sites.project_id', projectId)
             .order('check_date', { ascending: false })
             .limit(20);
         if (site_id)
@@ -595,15 +596,19 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
             .eq('id', site_id)
             .eq('project_id', projectId)
             .maybeSingle();
-        if (siteErr || !site)
-            return txt(`Error: Site not found — ${siteErr?.message ?? 'not found'}`);
+        if (siteErr)
+            return toolError({ error: 'Unable to load site', code: 'internal_error' });
+        if (!site)
+            return toolError({ error: 'Site not found', code: 'not_found' });
         // 2. Fetch latest domain_health
-        const { data: healthRows } = await db()
+        const { data: healthRows, error: healthError } = await db()
             .from('domain_health')
             .select('spf_valid, dkim_valid, dmarc_valid, bounce_rate, complaint_rate, warmup_day, warmup_daily_limit, delivery_rate, total_sent')
             .eq('site_id', site_id)
             .order('check_date', { ascending: false })
             .limit(1);
+        if (healthError)
+            return toolError({ error: 'Unable to load domain health', code: 'internal_error' });
         const health = (healthRows ?? [])[0];
         const spfValid = health?.spf_valid ?? null; // null = not checked yet (#3904)
         const spfFailed = spfValid === false;
@@ -615,18 +620,16 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
         const warmupDailyLimit = health?.warmup_daily_limit ?? null;
         // 3. Fetch recent 7-day email_log stats
         const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
-        const { data: recentLogs } = await db()
+        const { data: recentLogs, error: logsError } = await db()
             .from('email_log')
             .select("status, opened_at, clicked_at, bounced_at, contact_id, to_email")
             .eq('project_id', projectId)
             .eq('site_id', site_id)
             .gte('sent_at', sevenDaysAgo);
+        if (logsError)
+            return toolError({ error: 'Unable to load send history', code: 'internal_error' });
         const logs = recentLogs ?? [];
-        const totalSent = logs.length;
-        const bounced = logs.filter(isBouncedRow).length;
-        const complained = logs.filter(isComplainedRow).length;
-        const delivered = logs.filter(isDeliveredRow).length;
-        const opened = countPeople(logs, isOpenedRow);
+        const { sent: totalSent, bounced, complained, delivered, opened } = countEmailRows(logs);
         const bounceRate = percentRate(bounced, totalSent, 2) ?? 0;
         const complaintRate = percentRate(complained, totalSent, 2) ?? 0;
         const openRate = percentRate(opened, delivered, 2) ?? 0;
@@ -745,7 +748,8 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
             estimatedRecovery = '3-5 days';
         return j({
             site: { id: site.id, slug: site.slug, domain: site.sending_domain },
-            health_score: healthScore,
+            health_score: totalSent === 0 ? null : healthScore,
+            ...(totalSent === 0 ? { health_score_reason: 'no_send_data', reason: 'no_send_data' } : {}),
             recent_7d: {
                 total_sent: totalSent,
                 delivered,
@@ -765,7 +769,7 @@ Return ONLY valid JSON (no markdown fences): { "topics": [{ "title": "...", "rat
                 short_term: shortTerm.length > 0 ? shortTerm : ['Continue current sending practices'],
                 monitoring,
             },
-            estimated_recovery: issues.length === 0 ? 'No recovery needed — site is healthy' : estimatedRecovery,
+            ...(issues.some(issue => issue.type !== 'no_recent_sends') ? { estimated_recovery: estimatedRecovery } : {}),
         });
     });
 }

package/build/tools/analytics.d.ts

@@ -28,10 +28,11 @@ export declare function computeAnalyticsMetrics(rows: EmailLogRow[], eventCounts
     clicked: number;
 }): AnalyticsMetrics;
 export declare function computeSenderHealthScore(metrics: {
+    sent: number;
     bounce_rate: number;
     complaint_rate: number;
     unsubscribe_rate: number;
     open_rate: number;
-}, trackingEnabled: boolean): number;
+}, trackingEnabled: boolean): number | null;
 export declare function registerAnalyticsTools(server: McpServer): void;
 export {};

package/build/tools/analytics.js

@@ -1,4 +1,4 @@
-import { readPeriodCampaigns, campaignPeriodFields } from "@sendinel/domain";
+import { readPeriodCampaigns, campaignPeriodFields, filterPlanContacts } from "@sendinel/domain";
 import { isTrueConversionEvent, TRUE_CONVERSION_DEFINITION } from "@sendinel/domain";
 import { percentRate, groupMetricRows, readRevenue, isComplainedRow, isOpenedRow, countPeople, isClickedRow, summarizeEmailRows, countEmailRows, isDeliveredRow, isBouncedRow, fetchAllRows, readAllRows } from "@sendinel/domain";
 import { z } from 'zod';
@@ -7,6 +7,7 @@ import { getProjectId } from '../project.js';
 import { resolveProjectClient } from '../byod-client.js';
 import { decrypt } from '../crypto.js';
 import { logAudit } from '../audit.js';
+import { dbToolError, toolError } from '../lib/db-error.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 const percent = (rate) => `${(rate * 100).toFixed(1)}%`;
@@ -21,6 +22,8 @@ export function computeAnalyticsMetrics(rows, eventCounts) {
         complaint_rate: metrics.complaint_rate ?? 0, unsubscribe_rate: metrics.unsubscribe_rate ?? 0 };
 }
 export function computeSenderHealthScore(metrics, trackingEnabled) {
+    if (metrics.sent === 0)
+        return null;
     let score = 100;
     if (metrics.bounce_rate > 0.05)
         score -= 40;
@@ -462,6 +465,11 @@ export function registerAnalyticsTools(server) {
     }, async ({ site_id, start_date, end_date }) => {
         const projectId = getProjectId();
         const end = end_date ?? new Date().toISOString().slice(0, 10);
+        const validDate = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value) &&
+            Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+        if (!validDate(start_date) || !validDate(end) || start_date > end) {
+            return toolError({ error: 'Use valid YYYY-MM-DD dates with start_date on or before end_date', code: 'validation_failed' });
+        }
         const { data: site, error: siteError } = await db()
             .from('sites')
             .select('tracking_enabled')
@@ -469,7 +477,9 @@ export function registerAnalyticsTools(server) {
             .eq('id', site_id)
             .maybeSingle();
         if (siteError)
-            return { content: [{ type: 'text', text: `Error: ${siteError.message}` }] };
+            return toolError({ error: 'Unable to load site', code: 'internal_error' });
+        if (!site)
+            return toolError({ error: 'Site not found', code: 'not_found' });
         const trackingEnabled = site?.tracking_enabled ?? false;
         const { data, error, pageCount: logPageCount } = await fetchAllRows(async (offset, limit) => db()
             .from('email_log')
@@ -481,7 +491,7 @@ export function registerAnalyticsTools(server) {
             .order('id', { ascending: true })
             .range(offset, offset + limit - 1));
         if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+            return toolError(dbToolError(error));
         const rows = (data ?? []);
         let eventCounts = { opened: 0, clicked: 0 };
         let eventRows = [];
@@ -498,7 +508,7 @@ export function registerAnalyticsTools(server) {
                 .order('id', { ascending: true })
                 .range(offset, offset + limit - 1));
             if (eventsError)
-                return { content: [{ type: 'text', text: `Error: ${eventsError.message}` }] };
+                return toolError(dbToolError(eventsError));
             eventRows = events ?? [];
             eventPageCount = pageCount;
             const messageIds = new Set(rows.map(row => row.provider_message_id).filter((id) => Boolean(id)));
@@ -511,14 +521,14 @@ export function registerAnalyticsTools(server) {
         const periodDays = daysBetween(start_date, end);
         const priorStart = dateOnly(addDays(new Date(`${start_date}T00:00:00Z`), -periodDays));
         const priorEnd = dateOnly(addDays(new Date(`${start_date}T00:00:00Z`), -1));
-        const { data: subscribers, error: subscribersError, pageCount: subscriberPageCount } = await fetchAllRows(async (offset, limit) => db()
+        const { data: subscribers, error: subscribersError, pageCount: subscriberPageCount } = await fetchAllRows(async (offset, limit) => filterPlanContacts(db()
             .from('subscribers')
             .select('created_at, last_engaged_at, last_opened_at, last_clicked_at')
-            .eq('project_id', projectId)
+            .eq('project_id', projectId))
             .order('id', { ascending: true })
             .range(offset, offset + limit - 1));
         if (subscribersError)
-            return { content: [{ type: 'text', text: `Error: ${subscribersError.message}` }] };
+            return toolError(dbToolError(subscribersError));
         const subscriberRows = (subscribers ?? []);
         const currentNew = subscriberRows.filter(s => s.created_at && s.created_at >= `${start_date}T00:00:00Z` && s.created_at <= `${end}T23:59:59Z`).length;
         const priorNew = subscriberRows.filter(s => s.created_at && s.created_at >= `${priorStart}T00:00:00Z` && s.created_at <= `${priorEnd}T23:59:59Z`).length;
@@ -540,6 +550,7 @@ export function registerAnalyticsTools(server) {
             list_growth_rate: subscriberRows.length > 0 ? pctNumber(currentNew / subscriberRows.length) : 0,
             inactive_pct: subscriberRows.length > 0 ? pctNumber(inactive / subscriberRows.length) : 0,
             sender_health_score: computeSenderHealthScore(metrics, trackingEnabled),
+            ...(metrics.sent === 0 ? { sender_health_score_reason: 'no_send_data', reason: 'no_send_data' } : {}),
             coverage: {
                 log_rows_scanned: rows.length,
                 log_page_count: logPageCount,
@@ -890,7 +901,8 @@ export function registerAnalyticsTools(server) {
             return txt(`Error: ${attributionError.message}`);
         const scopedAttributionRows = attributionRows ?? [];
         const computeMetrics = (set, counts) => {
-            const total = counts?.sent ?? set.length;
+            const sharedCounts = counts ?? countEmailRows(set);
+            const total = sharedCounts.sent;
             const delivered = counts?.delivered ?? set.filter(isDeliveredRow).length;
             const opened = counts?.opened ?? countPeople(set, isOpenedRow);
             const clicked = counts?.clicked ?? countPeople(set, isClickedRow);

package/build/tools/approvals.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
+import { dbToolError, toolError } from '../lib/db-error.js';
 import { checkApproval } from '../lib/action-approvals.js';
 import { confirmApproval, confirmApprovalInput } from '../lib/approval-chat-confirm.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
@@ -42,7 +43,7 @@ export function registerApprovalTools(server, options) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List all pending approval requests for this project. Excludes expired requests without mutating them. Shows what actions are waiting for human approval.',
+        description: 'List unexpired pending approval requests for this project. Expired rows are excluded even before the expiry cron runs.',
         inputSchema: {},
     }, async () => {
         const { data, error } = await db()
@@ -54,7 +55,7 @@ export function registerApprovalTools(server, options) {
             .order('requested_at', { ascending: false })
             .limit(25);
         if (error)
-            return j({ error: error.message, code: 'INTERNAL_ERROR' });
+            return toolError(dbToolError(error));
         return j({ pending: data ?? [], count: data?.length ?? 0 });
     });
 }

package/build/tools/campaigns.js

@@ -1,3 +1,4 @@
+import { dbErrorResult } from '../lib/db-errors.js';
 import { resolveCampaignReentry, readCampaignPeriods, campaignPeriodFields } from "@sendinel/domain";
 import { CAMPAIGN_BRANCH_CONDITIONS, campaignBranchConditionValue, isContactPropertyConditionList, STEP_PROPERTY_CONDITIONS_ERROR, validateStepPropertyRules } from "@sendinel/domain";
 import { z } from 'zod';
@@ -12,6 +13,7 @@ import { ensureReplyActionSecretConfigured, mintReplyAction, } from '@sendinel/d
 import { finishCampaignEdit, resumeCampaignEdit, TRIGGER_EDIT_SELECT } from '../lib/campaign-trigger-approval.js';
 import { adminDb, db, requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
+import { dbToolError, toolError } from '../lib/db-error.js';
 import { checkPlanLimit } from '../plan-limits.js';
 import { buildVoicePrompt, buildEmailSystemPrompt, deriveTemplateVariables, validateTemplate } from '../lib/voice.js';
 import { fireWebhookEvent } from '../lib/webhook-events.js';
@@ -382,10 +384,12 @@ async function campaignInProject(campaignId) {
     return Boolean(data);
 }
 /** Mirrors validateTarget() in the branches REST route. */
-async function validateBranchTarget(campaignId, action, targetStepId, targetCampaignId) {
+async function validateBranchTarget(campaignId, fromStepId, action, targetStepId, targetCampaignId) {
     if (action === 'goto_step') {
         if (!targetStepId)
             return 'target_step_id is required for goto_step';
+        if (targetStepId === fromStepId)
+            return 'goto_step cannot target its own source step';
         const { data } = await db()
             .from('campaign_steps')
             .select('id')
@@ -398,6 +402,8 @@ async function validateBranchTarget(campaignId, action, targetStepId, targetCamp
     if (action === 'goto_campaign') {
         if (!targetCampaignId)
             return 'target_campaign_id is required for goto_campaign';
+        if (targetCampaignId === campaignId)
+            return 'goto_campaign cannot target its own campaign';
         if (!(await campaignInProject(targetCampaignId)))
             return 'target_campaign_id must be a campaign in this project';
     }
@@ -882,40 +888,56 @@ export function registerCampaignTools(server) {
             send_only_if_event: z.string().trim().min(1).optional().describe('Send this step only if the contact has an event with this name by send time; otherwise skip it and continue the journey.'),
         },
     }, async ({ campaign_id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, variant_label, survey_id, brand_asset_ids, skip_if_event, send_only_if_event, skip_if_property, send_only_if_property }) => {
-        const properties = validateStepPropertyRules({ skip_if_property, send_only_if_property });
-        if (!properties.ok)
-            return j({ error: properties.error, code: "INVALID_INPUT" });
-        const renderVars = {};
-        if (survey_id) {
-            const surveyLink = await resolveSurveyShortLink(db(), getProjectId(), survey_id);
-            if (!surveyLink)
-                return j({ error: 'Survey has no short link yet', code: 'SURVEY_LINK_NOT_READY' });
-            renderVars.survey_link = surveyLink;
+        try {
+            const properties = validateStepPropertyRules({ skip_if_property, send_only_if_property });
+            if (!properties.ok)
+                return j({ error: properties.error, code: "INVALID_INPUT" });
+            const { data: campaign, error: campaignError } = await db()
+                .schema('email')
+                .from('campaigns')
+                .select('id')
+                .eq('id', campaign_id)
+                .eq('project_id', getProjectId())
+                .maybeSingle();
+            if (campaignError)
+                return dbErrorResult(campaignError);
+            if (!campaign)
+                return { ...j({ error: 'Campaign not found.', code: 'not_found' }), isError: true };
+            const renderVars = {};
+            if (survey_id) {
+                const surveyLink = await resolveSurveyShortLink(db(), getProjectId(), survey_id);
+                if (!surveyLink)
+                    return j({ error: 'Survey has no short link yet', code: 'SURVEY_LINK_NOT_READY' });
+                renderVars.survey_link = surveyLink;
+            }
+            const renderedSubject = survey_id ? renderTemplateVars(subject, renderVars) : subject;
+            const normalizedBlocks = blocks ? normalizeComposerBlocks(blocks) : undefined;
+            const htmlFromBlocks = normalizedBlocks?.length ? blocksToHtml(normalizedBlocks) : undefined;
+            const renderedHtml = body_html !== undefined && survey_id ? renderTemplateVars(body_html, renderVars) : body_html ?? htmlFromBlocks;
+            const renderedText = body_text !== undefined && survey_id ? renderTemplateVars(body_text, renderVars) : body_text;
+            const { data, error } = await db()
+                .from('campaign_steps')
+                .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null, send_only_if_event: send_only_if_event ?? null, ...properties.rules })
+                .select()
+                .single();
+            if (error)
+                return dbErrorResult(error);
+            await recordBrandAssetUsage({
+                client: db(),
+                projectId: getProjectId(),
+                source: 'campaign_step',
+                resourceId: data.id,
+                html: renderedHtml,
+                assetIds: brand_asset_ids,
+            }).catch((err) => {
+                console.warn('Failed to record brand asset usage for MCP campaign step:', err);
+            });
+            await logAudit({ action: 'campaign.step_created', resourceType: 'campaign_step', resourceId: data.id, details: { property_rules: properties.rules } });
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return dbErrorResult(error);
         }
-        const renderedSubject = survey_id ? renderTemplateVars(subject, renderVars) : subject;
-        const normalizedBlocks = blocks ? normalizeComposerBlocks(blocks) : undefined;
-        const htmlFromBlocks = normalizedBlocks?.length ? blocksToHtml(normalizedBlocks) : undefined;
-        const renderedHtml = body_html !== undefined && survey_id ? renderTemplateVars(body_html, renderVars) : body_html ?? htmlFromBlocks;
-        const renderedText = body_text !== undefined && survey_id ? renderTemplateVars(body_text, renderVars) : body_text;
-        const { data, error } = await db()
-            .from('campaign_steps')
-            .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null, send_only_if_event: send_only_if_event ?? null, ...properties.rules })
-            .select()
-            .single();
-        if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
-        await recordBrandAssetUsage({
-            client: db(),
-            projectId: getProjectId(),
-            source: 'campaign_step',
-            resourceId: data.id,
-            html: renderedHtml,
-            assetIds: brand_asset_ids,
-        }).catch((err) => {
-            console.warn('Failed to record brand asset usage for MCP campaign step:', err);
-        });
-        await logAudit({ action: 'campaign.step_created', resourceType: 'campaign_step', resourceId: data.id, details: { property_rules: properties.rules } });
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('update_campaign_status', {
         title: 'Update Campaign Status',
@@ -1589,7 +1611,7 @@ export function registerCampaignTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Clone an existing campaign (with all steps) into a new draft campaign',
+        description: 'Clone campaign steps into a draft. Trigger, audience, send class, re-entry, goals and branches are NOT copied; fields_not_copied and warnings explicitly identify these omissions. Review and configure before activation.',
         inputSchema: {
             campaign_id: z.string().uuid().describe('Source campaign to clone'),
             new_name: z.string().min(1).describe('Name for the cloned campaign'),
@@ -1603,11 +1625,13 @@ export function registerCampaignTools(server) {
             .eq('id', campaign_id)
             .eq('project_id', projectId)
             .maybeSingle();
-        if (fetchErr || !original)
-            return txt(`Error: Campaign not found — ${fetchErr?.message ?? 'not found'}`);
+        if (fetchErr)
+            return toolError(dbToolError(fetchErr));
+        if (!original)
+            return toolError({ error: 'Campaign not found', code: 'not_found' });
         const limit = await checkPlanLimit('active_campaigns');
         if (!limit.allowed)
-            return txt(`Active campaign limit reached (${limit.current}/${limit.limit}).`);
+            return toolError({ error: `Active campaign limit reached (${limit.current}/${limit.limit}).`, code: 'plan_limit' });
         const { data: newCampaign, error: createErr } = await db()
             .from('campaigns')
             .insert({
@@ -1623,7 +1647,7 @@ export function registerCampaignTools(server) {
             .select()
             .single();
         if (createErr)
-            return txt(`Error creating campaign: ${createErr.message}`);
+            return toolError(dbToolError(createErr));
         const steps = (original.campaign_steps ?? []).sort((a, b) => a.step_order - b.step_order);
         if (steps.length > 0) {
             const stepRows = steps.map((s) => ({
@@ -1638,9 +1662,18 @@ export function registerCampaignTools(server) {
             }));
             const { error: stepErr } = await db().from('campaign_steps').insert(stepRows);
             if (stepErr)
-                return txt(`Campaign created but steps failed: ${stepErr.message}`);
-        }
-        return j({ ...newCampaign, steps_copied: steps.length, cloned_from: campaign_id });
+                return toolError({ ...dbToolError(stepErr, 'Campaign created but copying steps failed'), campaign_id: newCampaign.id });
+        }
+        const copied = new Set(['project_id', 'site_id', 'name', 'type', 'description', 'sends_per_hour', 'requires_approval']);
+        const identity = new Set(['id', 'status', 'created_at', 'updated_at', 'campaign_steps']);
+        const fields_not_copied = [...new Set([
+                ...Object.keys(original).filter(key => !copied.has(key) && !identity.has(key)),
+                'trigger_type', 'trigger_event_name', 'trigger_tag', 'trigger_config', 'segment_id',
+                'send_class', 'unsub_footer_template', 'period_key', 'reentry_mode', 'campaign_goals', 'campaign_step_branches',
+            ])];
+        await logAudit({ action: 'campaign.cloned', resourceType: 'campaign', resourceId: newCampaign.id, details: { cloned_from: campaign_id, fields_not_copied } });
+        return j({ ...newCampaign, steps_copied: steps.length, cloned_from: campaign_id, fields_not_copied,
+            warnings: fields_not_copied.map(field => `${field} was not copied; review and configure the draft before activation.`) });
     });
     server.registerTool('list_sequence_templates', {
         title: 'List Sequence Templates',
@@ -3831,14 +3864,20 @@ Return ONLY valid JSON with this exact shape:
     }, async ({ campaign_id, from_step_id, condition_type, condition_value, action, target_step_id, target_campaign_id, priority }) => {
         const conditionValue = campaignBranchConditionValue(condition_type, condition_value);
         if (!conditionValue.ok)
-            return { ...j({ error: conditionValue.error, code: 'INVALID_CONDITION_VALUE' }), isError: true };
+            return { ...j({ error: conditionValue.error, code: 'validation_failed' }), isError: true };
         if (!(await campaignInProject(campaign_id)))
-            return j({ error: 'Campaign not found in this project', code: 'CAMPAIGN_NOT_FOUND' });
+            return toolError({ error: 'Campaign not found in this project', code: 'not_found' });
+        const { data: sourceStep, error: sourceError } = await db().from('campaign_steps').select('id')
+            .eq('id', from_step_id).eq('campaign_id', campaign_id).maybeSingle();
+        if (sourceError)
+            return toolError(dbToolError(sourceError));
+        if (!sourceStep)
+            return toolError({ error: 'from_step_id must be a step in this campaign', code: 'validation_failed' });
         // Same requirement the REST route enforces: an action naming a target must have one,
         // and that target must belong to this project.
-        const targetError = await validateBranchTarget(campaign_id, action, target_step_id ?? null, target_campaign_id ?? null);
+        const targetError = await validateBranchTarget(campaign_id, from_step_id, action, target_step_id ?? null, target_campaign_id ?? null);
         if (targetError)
-            return j({ error: targetError, code: 'INVALID_TARGET' });
+            return toolError({ error: targetError, code: 'validation_failed' });
         const { data, error } = await db()
             .from('campaign_step_branches')
             .insert({
@@ -3854,9 +3893,14 @@ Return ONLY valid JSON with this exact shape:
             .select('id, from_step_id, condition_type, condition_value, action, target_step_id, target_campaign_id, priority')
             .single();
         if (error)
-            return j({ error: error.message });
+            return toolError(dbToolError(error));
         await logAudit({ action: 'add_campaign_branch', resourceType: 'campaign', resourceId: campaign_id, details: { branch_id: data?.id, condition_type, branch_action: action } }).catch(() => { });
-        return j({ success: true, branch: data });
+        // Read after insertion so a tie already committed by a concurrent request is visible.
+        const { data: peers, error: peerError } = await db().from('campaign_step_branches').select('id')
+            .eq('campaign_id', campaign_id).eq('from_step_id', from_step_id).eq('priority', priority ?? 0).neq('id', data.id);
+        const warnings = peerError ? ['Branch saved, but priority ties could not be checked.']
+            : peers?.length ? ['Another branch on this step has the same priority; evaluation order may be ambiguous.'] : [];
+        return j({ success: true, branch: data, warnings });
     });
     server.registerTool('remove_campaign_branch', {
         title: 'Remove Campaign Branch',