@sendinel/mcp-server 1.0.98 → 1.0.100

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/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.',
@@ -1131,21 +1166,27 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         if (!rows.length)
             return j([]);
         const companyIds = rows.map((company) => company.id);
-        const { data: subscribers, error: subscriberError } = await db()
-            .from('subscribers')
-            .select('company_id, engagement_score, total_opens, total_clicks, lifecycle_stage, last_engaged_at')
-            .eq('project_id', projectId)
-            .in('company_id', companyIds);
-        if (subscriberError)
-            return txt(`Error: ${subscriberError.message}`);
         const grouped = new Map();
-        for (const subscriber of subscribers ?? []) {
-            const companyId = typeof subscriber.company_id === 'string' ? subscriber.company_id : null;
-            if (!companyId)
-                continue;
-            const bucket = grouped.get(companyId) ?? [];
-            bucket.push(subscriber);
-            grouped.set(companyId, bucket);
+        for (let offset = 0;; offset += 1000) {
+            const { data: subscribers, error: subscriberError } = await db()
+                .from('subscribers')
+                .select('company_id, engagement_score, total_opens, total_clicks, lifecycle_stage, last_engaged_at')
+                .eq('project_id', projectId)
+                .in('company_id', companyIds)
+                .order('id')
+                .range(offset, offset + 999);
+            if (subscriberError)
+                return txt(`Error: ${subscriberError.message}`);
+            for (const subscriber of subscribers ?? []) {
+                const companyId = typeof subscriber.company_id === 'string' ? subscriber.company_id : null;
+                if (!companyId)
+                    continue;
+                const bucket = grouped.get(companyId) ?? [];
+                bucket.push(subscriber);
+                grouped.set(companyId, bucket);
+            }
+            if ((subscribers ?? []).length < 1000)
+                break;
         }
         return j(rows.map((company) => ({
             ...company,
@@ -2161,11 +2202,21 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 return j({ inactive_count: 0, sample: [], message: 'No subscribed contacts for this site.' });
             q = q.in('id', ids);
         }
-        const { data: suppressed } = await db()
-            .from('suppressions')
-            .select('email')
-            .eq('project_id', projectId);
-        const suppressedSet = new Set((suppressed ?? []).map((s) => s.email));
+        const suppressedSet = new Set();
+        for (let offset = 0;; offset += 1000) {
+            const { data: suppressed, error: suppressionError } = await db()
+                .from('suppressions')
+                .select('email')
+                .eq('project_id', projectId)
+                .order('email')
+                .range(offset, offset + 999);
+            if (suppressionError)
+                return txt(`Error: ${suppressionError.message}`);
+            for (const suppression of suppressed ?? [])
+                suppressedSet.add(suppression.email);
+            if ((suppressed ?? []).length < 1000)
+                break;
+        }
         const { data: contacts, error } = await q.order('engagement_score', { ascending: true }).limit(sampleLimit);
         if (error)
             return txt(`Error: ${error.message}`);

package/package.json

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