@sendinel/mcp-server 1.0.97 → 1.0.99

package/README.md

@@ -12,7 +12,13 @@ AI-controlled email operations control plane for campaigns, contacts, segments,
 
 ## Tool groups
 
-Sendinel currently exposes 35 tool groups and 339 tools (gateway mode exposes 4 meta-tools, sharing how_to with full mode). These counts are checked against the tool registry in CI, so this table matches what ships.
+`emit_contact_event` (contacts, write scope) records an event and can enroll
+contacts into active sending campaigns. It requires standard human approval,
+preserves REST outcomes, and redacts failures. See the
+[event-triggered campaign guide](../../docs/event-triggered-campaigns.md) for
+inputs, idempotency, subscription requirements, and conditional step examples.
+
+Sendinel currently exposes 35 tool groups and 340 tools (gateway mode exposes 4 meta-tools, sharing how_to with full mode). These counts are checked against the tool registry in CI, so this table matches what ships.
 
 | Group | Count | Purpose |
 |-------|-------|---------|
@@ -28,7 +34,7 @@ Sendinel currently exposes 35 tool groups and 339 tools (gateway mode exposes 4
 | `cloud-import` | 6 | Cloud storage import |
 | `compound` | 4 | Higher-level campaign/template/site setup and delivery diagnosis workflows |
 | `connector` | 6 | BYOD connector status, table discovery, schema/view setup, mapping, resync |
-| `contacts` | 38 | Subscriber CRUD, saved views, tags, email log, suppression, merge, timeline |
+| `contacts` | 39 | Subscriber CRUD, saved views, tags, email log, suppression, merge, timeline |
 | `content` | 14 | Content blocks, gated asset links, blog ingest and auto-publish, sources |
 | `data` | 19 | Platform connectors, imports, API keys, migration jobs, notifications, tenant export |
 | `data-proposals` | 3 | Data-derived campaign proposal generation, listing, approval |

package/build/db.d.ts

@@ -3,6 +3,7 @@ export type V1CallOptions = {
     method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
     body?: unknown;
     query?: Record<string, string>;
+    idempotencyKey?: string;
 };
 export type V1CallResult = {
     ok: true;

package/build/lib/action-approvals.js

@@ -54,6 +54,7 @@ const GATED_ACTIONS = new Set([
     'tenant_export_full', // copies all customer data out of Sendinel
     'enroll_contact', // starts real emails to a contact
     'identify_subscriber', // may enroll a new signup in sending campaigns
+    'emit_contact_event', // may enroll a real contact in active sending campaigns
     'enroll_automation', // starts automated messages to a contact
     'enroll_in_escalation_ladder', // starts email/SMS escalation to a contact
     'set_contact_sms_consent', // changes the consent record that allows texting

package/build/lib/v1-client.js

@@ -28,6 +28,7 @@ export async function callSendinelV1(path, opts = {}) {
             Authorization: `Bearer ${apiKey}`,
             'X-Sendinel-Project-Id': getProjectId(),
             'Content-Type': 'application/json',
+            ...(opts.idempotencyKey ? { 'Idempotency-Key': opts.idempotencyKey } : {}),
         },
         ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
     });

package/build/server.js

@@ -82,7 +82,7 @@ export const ALL_TOOL_GROUPS = Object.keys(GROUP_REGISTRY);
 const WRITE_TOOLS = new Set([
     'recheck_domain_dns',
     'mark_agent_message', 'draft_agent_reply', 'create_agent_mailbox',
-    'add_subscriber', 'identify_subscriber', 'import_subscribers', 'update_subscriber', 'bulk_update_subscribers',
+    'add_subscriber', 'identify_subscriber', 'emit_contact_event', 'import_subscribers', 'update_subscriber', 'bulk_update_subscribers',
     'create_subscriber_view', 'update_subscriber_view', 'delete_subscriber_view',
     'enrich_subscriber',
     'create_campaign', 'update_campaign', 'delete_campaign', 'add_campaign_step', 'update_campaign_status',

package/build/tools/campaigns.js

@@ -1,7 +1,7 @@
 import { CAMPAIGN_BRANCH_CONDITIONS, campaignBranchConditionValue, isContactPropertyConditionList, STEP_PROPERTY_CONDITIONS_ERROR, validateStepPropertyRules } from "@sendinel/domain";
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { assertSendAccepted, SendRefusedError, BLOCKING_CONTENT_ISSUE_KINDS, computeSendContentKey, findContentIssues, sendingHostOf, NAME_FALLBACKS, ONE_SEND_MATCH_STATUSES, ONE_SEND_SENT_STATUSES, ONE_SEND_WINDOW_DAYS, normalizeTriggerConfig, renderTemplateString as renderTemplateVars, resolveBrandTokens, brandWarnings, readAllRows, } from '@sendinel/domain';
+import { assertSendAccepted, providerSendError, sendError, SendRefusedError, BLOCKING_CONTENT_ISSUE_KINDS, computeSendContentKey, findContentIssues, sendingHostOf, NAME_FALLBACKS, ONE_SEND_MATCH_STATUSES, ONE_SEND_SENT_STATUSES, ONE_SEND_WINDOW_DAYS, normalizeTriggerConfig, renderTemplateString as renderTemplateVars, resolveBrandTokens, brandWarnings, readAllRows, } from '@sendinel/domain';
 // Subpath import, not the barrel above -- reply-actions.ts uses node:crypto,
 // and MCP-server-side that's fine (this never runs in an Edge Function), but
 // keeping it off the shared barrel avoids re-creating the Edge-Function
@@ -2331,7 +2331,7 @@ Do not include body_html in your response; Sendinel renders body_html from block
             .limit(1)
             .maybeSingle();
         if (suppression)
-            return txt(`Error: Recipient suppressed — ${suppression.reason}`);
+            return { ...txt('Error: Recipient is suppressed'), code: 'invalid_recipient' };
         // Idempotency check
         if (idempotency_key) {
             const { data: existing } = await db()
@@ -2369,8 +2369,10 @@ Do not include body_html in your response; Sendinel renders body_html from block
                 .eq('id', template_id)
                 .eq('project_id', projectId)
                 .maybeSingle();
-            if (templateError)
-                return txt(`Error: ${templateError.message}`);
+            if (templateError) {
+                console.error('MCP send template lookup failed:', templateError);
+                return { ...txt('Error: Internal server error'), ...sendError('internal_error') };
+            }
             if (!template)
                 return txt('Error: Template not found');
             const { data: project } = await adminDb().from('projects').select('brand_settings').eq('id', projectId).maybeSingle();
@@ -2425,10 +2427,13 @@ Do not include body_html in your response; Sendinel renders body_html from block
             assertSendAccepted(sendResult);
         }
         catch (error) {
+            console.error('MCP transactional send failed:', error);
             if (error instanceof SendRefusedError) {
                 await db().from('email_log').insert({ project_id: projectId, site_id, to_email: to, from_email: site.from_email, subject: resolvedSubject, category: 'transactional', status: 'failed', error_message: error.message });
             }
-            return txt(`Error: Send failed — ${error instanceof Error ? error.message : 'unknown provider error'}`);
+            const safe = providerSendError(error);
+            const code = error instanceof SendRefusedError ? error.refusal.code : safe.code;
+            return { ...txt(`Error: Send failed — ${safe.error} (${code})`), error: safe.error, code };
         }
         // Log to email_log
         const { data: logRow } = await db().from('email_log').insert({

package/build/tools/contacts.js

@@ -536,6 +536,41 @@ async function exportSubscriberData(projectId, contactId) {
     };
 }
 export function registerContactTools(server) {
+    server.registerTool('emit_contact_event', {
+        title: 'Emit Contact Event',
+        description: 'Record a contact event through POST /api/v1/events and enroll matching active triggered campaigns. Can start real sends; requires standard approval. Returns the REST outcome and sendability unchanged. Does not subscribe the contact or update contact properties.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: {
+            approval_id: z.string().uuid().optional().describe('Call once to request approval, then repeat the same arguments with the approved approval_id.'),
+            email: z.string().email(),
+            event: z.string().trim().min(1),
+            data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            idempotency_key: z.string().min(1).optional().describe('Sent as Idempotency-Key. Reuse with the same event payload when retrying.'),
+        },
+    }, withApproval('emit_contact_event', async ({ email, event, data, idempotency_key }) => {
+        // Never forward raw transport, database or provider errors to the MCP caller.
+        // Only known public codes survive; even a returned message may contain internal text.
+        const publicCodes = new Set([
+            'contact_limit', 'invalid_consent_site', 'contact_create_failed', 'event_record_failed', 'event_intake_failed',
+            'IDEMPOTENCY_UNAVAILABLE', 'IDEMPOTENCY_KEY_REUSED', 'IDEMPOTENCY_IN_FLIGHT',
+        ]);
+        try {
+            const result = await callSendinelV1('/api/v1/events', {
+                method: 'POST',
+                body: { email, event, ...(data !== undefined ? { data } : {}) },
+                ...(idempotency_key ? { idempotencyKey: idempotency_key } : {}),
+            });
+            if (result.ok)
+                return j(result.data);
+            const payload = result.error && typeof result.error === 'object' && 'error' in result.error
+                && result.error.error && typeof result.error.error === 'object' ? result.error.error : result.error;
+            const code = payload && typeof payload === 'object' && 'code' in payload ? payload.code : undefined;
+            return { ...j({ code: typeof code === 'string' && publicCodes.has(code) ? code : 'event_intake_failed', error: 'Could not emit contact event' }), isError: true };
+        }
+        catch {
+            return { ...j({ code: 'event_intake_failed', error: 'Could not emit contact event' }), isError: true };
+        }
+    }));
     server.registerTool('identify_subscriber', {
         title: 'Identify Subscriber',
         description: 'Identify or update a contact through the v1 identify API. Optional signup/customer consent subscribes new or existing contacts without overriding opt-outs. Customer consent requires a topic; consent requires site_id. Without consent, site_id retains legacy create-only subscription behavior and returns a warning.',

package/package.json

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