@sendinel/mcp-server 1.0.186 → 1.0.188

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

@@ -119,6 +119,8 @@ type ToolResult = {
     }>;
     isError?: boolean;
 };
+/** Validate live targets before any approval is requested or consumed, including registry gates. */
+export declare function registerApprovalPreflight(action: string, fn: (params: Record<string, unknown>) => Promise<ToolResult | null | undefined>): void;
 export declare function approvalSatisfied(action: string): boolean;
 /** Catch preview/draft branches that historically returned before their hand-written gate.
  * Existing gated execution paths retain their frozen-payload approval flow. */

package/build/lib/action-approvals.js

@@ -608,6 +608,11 @@ async function checkApprovalState(approvalId, options = {}) {
         ...(sandboxDecision ? { decision_channel: 'sandbox' } : {}),
     };
 }
+const approvalPreflights = new Map();
+/** Validate live targets before any approval is requested or consumed, including registry gates. */
+export function registerApprovalPreflight(action, fn) {
+    approvalPreflights.set(action, fn);
+}
 function toolText(value) {
     return { content: [{ type: 'text', text: value }] };
 }
@@ -663,6 +668,11 @@ export function withApproval(action, handler, options = {}) {
         const decision = await assertChannelCanExecute(action, params, channelContext);
         if (!decision.allowed)
             return toolText(decision.reason ?? 'This channel cannot request this action.');
+        // Use exactly the payload passed to requestApproval/checkApproval. Expected failures
+        // return toolError; unexpected exceptions reach the normal internal_error boundary.
+        const preflightResult = await approvalPreflights.get(action)?.(params);
+        if (preflightResult)
+            return preflightResult;
         let decidedBy;
         let decisionChannel;
         let consumedAt;

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

@@ -65,6 +65,19 @@ export const HOW_TO_RECIPES = [
         gotchas: [projectRule, 'An empty list means there is no campaign to report. Distinguish drafts and zero sends from failed reads. Raw total_opened/total_clicked are event counters, not unique people.'],
         done_when: 'The chosen campaign and its unique engagement counts are reported, with unknown counts and incomplete sends explained.',
     },
+    {
+        id: 'analytics-summary', title: 'Summarize project email analytics',
+        when_to_use: 'Review sender-level email performance and recent campaigns for one project.',
+        synonyms: ['analytics summary', 'pull an analytics summary', 'analytics for my project', 'stats summary', 'project stats', 'performance overview', 'how are my emails doing'],
+        requires: { scopes: ['read'], tester_ok: true },
+        steps: [
+            { n: 1, tool: 'get_sites', args_example: {}, note: 'Choose the sender for the project whose analytics you want to review.' },
+            { n: 2, tool: 'get_stats', args_example: { site_id: from(1, '0.id'), start_date: '2026-10-01' }, note: 'Replace start_date with the beginning of the requested reporting period; end_date defaults to today.' },
+            { n: 3, tool: 'list_campaigns', args_example: { site_id: from(1, '0.id'), limit: 25 }, note: 'Use campaign metrics to add context to sender-wide performance; newest-created first, not newest-sent.' },
+        ],
+        gotchas: [projectRule, 'get_stats is sender-wide for the selected site, not campaign-specific. Distinguish drafts from sent campaigns and call out the reporting period.'],
+        done_when: 'Summarize the selected sender’s metrics and reporting period, with recent campaign context and unknowns called out.',
+    },
     {
         id: 'add-or-import-contacts', title: 'Add a contact or import contacts',
         when_to_use: 'Subscribe a single contact to a sender, or bulk import an opted-in list.',

package/build/tools/agent-mailboxes.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { checkAgentMailboxLimit, validateMailboxDisplayName } from '@sendinel/domain';
 import { db, requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
-import { withApproval, approvalExcerpt } from '../lib/action-approvals.js';
+import { withApproval, approvalExcerpt, registerApprovalPreflight } from '../lib/action-approvals.js';
 import { toolError, formatZodError } from '../lib/db-error.js';
 import { checked, mailboxDb, mailboxAudit, messageOutput, resolveMailbox, sendAgentReply, visibleMessage, visibleMessages, MailboxError } from '../lib/agent-mailbox.js';
 const j = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
@@ -51,12 +51,39 @@ const draftReplySchema = z.object({
 const createMailboxSchema = z.object({
     local_part: z.string().toLowerCase().regex(/^[a-z0-9][a-z0-9._+-]{0,63}$/),
     domain: z.string().toLowerCase().regex(/^agents\.[a-z0-9.-]+\.[a-z]{2,}$/),
-    display_name: z.string().max(200).regex(/^[^\r\n\u0000]*$/).optional(),
+    display_name: z.string().max(200).refine(value => validateMailboxDisplayName(value).valid, { message: 'Display name must be plain text without HTML, control characters, or bidirectional formatting characters.' }).optional(),
     mcp_connection_id: z.string().uuid(),
     site_id: z.string().uuid().optional(),
     daily_send_cap: z.number().int().positive().optional().default(50),
     approval_id,
 });
+async function createMailboxPreflight(params) {
+    const actorId = requestContext()?.actorId;
+    if (!actorId)
+        return toolError({ code: 'forbidden', error: 'An authenticated admin login is required to create a mailbox' });
+    const projectId = getProjectId();
+    const { data: tokenRow, error: tokenErr } = await mailboxDb().from('mcp_oauth_tokens')
+        .select('id, expires_at, revoked_at, user_id, project_id')
+        .eq('id', params.mcp_connection_id).eq('project_id', projectId).eq('user_id', actorId)
+        .is('revoked_at', null).maybeSingle();
+    if (tokenErr)
+        throw tokenErr;
+    const tokenExpired = !tokenRow || (tokenRow.expires_at != null &&
+        (!Number.isFinite(Date.parse(tokenRow.expires_at)) || Date.parse(tokenRow.expires_at) <= Date.now()));
+    if (tokenExpired) {
+        return toolError({ code: 'not_found', error: 'No active OAuth connection with that id for this login in this project.' });
+    }
+    if (params.site_id) {
+        const { data: siteRow, error: siteErr } = await mailboxDb().from('sites').select('id')
+            .eq('id', params.site_id).eq('project_id', projectId).maybeSingle();
+        if (siteErr)
+            throw siteErr;
+        if (!siteRow)
+            return toolError({ code: 'not_found', error: 'Site not found in this project.' });
+    }
+    return null;
+}
+registerApprovalPreflight('create_agent_mailbox', createMailboxPreflight);
 export function registerAgentMailboxTools(server) {
     server.registerTool('list_agent_inbox', {
         title: 'List Agent Inbox', description: 'Check your bound agent mailbox inbox. Unread first, then newest; filter by thread or status. Returns metadata and short text previews.' + outside,
@@ -173,9 +200,7 @@ export function registerAgentMailboxTools(server) {
     server.registerTool('create_agent_mailbox', {
         title: 'Create Agent Mailbox', description: 'Admin: create an agent mailbox inbox on an agents subdomain and bind it to an active OAuth connection owned by this login in this project. Atomically restricts that connection to the agent role. Optional site_id is its sending anchor; no site means replies fail. Extra scope grants are a later slice.' + gate,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        inputSchema: { local_part: z.string().toLowerCase().regex(/^[a-z0-9][a-z0-9._+-]{0,63}$/),
-            domain: z.string().toLowerCase().regex(/^agents\.[a-z0-9.-]+\.[a-z]{2,}$/), display_name: z.string().max(200).regex(/^[^\r\n\u0000]*$/).optional(),
-            mcp_connection_id: z.string().uuid(), site_id: z.string().uuid().optional(), daily_send_cap: z.number().int().positive().optional().default(50), approval_id },
+        inputSchema: createMailboxSchema.shape,
     }, wrapMailboxTool(async (args, extra) => {
         if (!args?.approval_id) {
             const missing = [];
@@ -207,27 +232,9 @@ export function registerAgentMailboxTools(server) {
                         : `This project's plan allows ${limit.limit} agent mailbox${limit.limit === 1 ? '' : 'es'} and it already has ${limit.current}.`,
                 }), isError: true };
         }
-        // Verify mcp_connection_id before issuing approval
-        const projectId = getProjectId();
-        const tokenQuery = mailboxDb().from('mcp_oauth_tokens').select('id, expires_at, revoked_at, user_id, project_id')
-            .eq('id', args.mcp_connection_id)
-            .eq('project_id', projectId)
-            .eq('user_id', actorId)
-            .is('revoked_at', null);
-        const { data: tokenRow, error: tokenErr } = await tokenQuery.maybeSingle();
-        const tokenExpired = !tokenRow || (tokenRow.expires_at && Date.parse(tokenRow.expires_at) <= Date.now());
-        if (tokenErr || tokenExpired) {
-            return toolError({ code: 'not_found', error: 'No active OAuth connection with that id for this login in this project.' });
-        }
-        if (args.site_id) {
-            const { data: siteRow, error: siteErr } = await mailboxDb().from('sites').select('id')
-                .eq('id', args.site_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
-            if (siteErr || !siteRow) {
-                return toolError({ code: 'not_found', error: 'Site not found in this project.' });
-            }
-        }
+        const preflight = await createMailboxPreflight(args);
+        if (preflight)
+            return preflight;
         const boundArgs = { ...args, login_actor_id: actorId };
         return withApproval('create_agent_mailbox', async (_approved) => {
             const mailbox = checked(await mailboxDb().rpc('provision_agent_mailbox', { p_project_id: getProjectId(),

package/package.json

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