@sendinel/mcp-server 1.0.124 → 1.0.126

package/README.md

@@ -18,7 +18,7 @@ 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 341 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.
+Sendinel currently exposes 35 tool groups and 342 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 |
 |-------|-------|---------|
@@ -27,7 +27,7 @@ Sendinel currently exposes 35 tool groups and 341 tools (gateway mode exposes 4
 | `advisor` | 6 | Campaign advisor: recommendations, benchmarks, subject/content/send-time guidance |
 | `ai-work` | 9 | AI work items, recommended segments, context events, agent proposals |
 | `analytics` | 15 | Stats, portfolio analytics, project switching, domain health, engagement, deliverability, revenue analytics |
-| `approvals` | 2 | Poll and list risk-tiered action approvals |
+| `approvals` | 3 | Poll and list risk-tiered action approvals |
 | `automations` | 7 | Automation triggers, previews, and response-gated escalation ladders |
 | `brand_kit` | 6 | Brand Core text import, media library upload/URL ingest, asset-context reads, project logo selection |
 | `campaigns` | 44 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates, convert imported campaigns |

package/build/db.d.ts

@@ -40,6 +40,7 @@ export declare function runWithClient<T>(client: any, fn: () => Promise<T>, requ
     actorType?: string;
     actorId?: string | null;
     oauthTokenId?: string | null;
+    chatConfirmEnabled?: boolean;
     invitationProjectIds?: string[] | null;
     authKind?: string | null;
     oauthClientId?: string | null;
@@ -66,6 +67,7 @@ export declare function requestContext(): {
     actorType?: string;
     actorId?: string | null;
     oauthTokenId?: string | null;
+    chatConfirmEnabled?: boolean;
     invitationProjectIds?: string[] | null;
     authKind?: string | null;
     oauthClientId?: string | null;

package/build/db.js

@@ -78,6 +78,7 @@ export function requestContext() {
             actorType: ctx.actorType,
             actorId: ctx.actorId,
             oauthTokenId: ctx.oauthTokenId,
+            chatConfirmEnabled: ctx.chatConfirmEnabled,
             invitationProjectIds: ctx.invitationProjectIds,
             authKind: ctx.authKind,
             oauthClientId: ctx.oauthClientId,

package/build/lib/action-approvals.js

@@ -311,6 +311,9 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
     catch { /* Missing display data omits the project line. */ }
     const approveUrl = approvalPageUrl(data.id);
     const previewText = buildApprovalPreview({ action, params: frozenParams, summary, projectName }).plain_summary;
+    const chatGuidance = tier === 'gated' && await humanApprovalEligible(action, getProjectId(), actor, true)
+        ? `\nAsk the user in plain chat: "${previewText.split('\n')[0].trim()}". Only after they say yes, call confirm_approval with approval_id, action, echo (the first line of preview_text) and user_reply (their exact words), then call the original tool again with approval_id.`
+        : '';
     const result = await elicitApproval({
         requires_approval: true,
         ...(await offerApprovalApp({ id: data.id, action, params: frozenParams, summary, tier, expires_at: expiresAt,
@@ -323,7 +326,7 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         approve_via: 'Open approve_url (works on a phone) or Dashboard → Settings → Pending Approvals',
         approve_url: approveUrl,
         preview_text: previewText,
-        message: `Tap to approve: ${approveUrl}\n${previewText}\nIt stays open for 24 hours. In a terminal with prompts you can also answer the on-screen Accept/Decline.`,
+        message: `Tap to approve: ${approveUrl}\n${previewText}\nIt stays open for 24 hours. In a terminal with prompts you can also answer the on-screen Accept/Decline.${chatGuidance}`,
     }, { action, params: frozenParams, summary, projectName }, getProjectId());
     if (result.decision_status === 'approved') {
         return { ...result, message: 'Approved. Call this tool again with the same arguments plus approval_id to run it.' };
@@ -382,9 +385,15 @@ export async function checkApproval(approvalId, options = {}) {
     }
     if (data.used_at || data.status === 'used')
         return { approved: false, status: 'consumed' };
+    // Chat decisions stay bound to the same live human grant at consumption, for every action.
+    if (data.status === 'approved' && data.decided_via === 'chat_confirm' &&
+        (requestContext()?.oauthTokenId !== data.oauth_token_id || requestContext()?.actorId !== data.decided_by ||
+            !await humanApprovalEligible(data.action, getProjectId(), requestContext(), true))) {
+        return { approved: false, status: 'human_decision_required' };
+    }
     if (data.status === 'approved' && (!isHumanApprovalChannel(data.decided_via) ||
         (isHumanRequestableAdminTool(data.action) && data.decided_via !== 'dashboard' &&
-            (!['mcp_app', 'mcp_elicitation'].includes(data.decided_via) ||
+            (!['mcp_app', 'mcp_elicitation', 'chat_confirm'].includes(data.decided_via) ||
                 !await humanApprovalEligible(data.action, getProjectId(), { projectId: getProjectId(),
                     actorId: data.decided_by, oauthTokenId: data.oauth_token_id, authKind: 'oauth', channelVerified: true }))))) {
         return { approved: false, status: 'human_decision_required' };
@@ -423,6 +432,8 @@ export async function checkApproval(approvalId, options = {}) {
         .eq('decided_via', data.decided_via)
         .eq('params', JSON.stringify(data.params))
         .gt('requested_at', new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString());
+    if (data.decided_via === 'chat_confirm')
+        claimQuery.eq('oauth_token_id', requestContext().oauthTokenId).eq('decided_by', requestContext().actorId);
     const boundClaim = data.payload_hash ? claimQuery.eq('payload_hash', data.payload_hash) : claimQuery.is('payload_hash', null);
     const { data: claimed, error: claimError } = await boundClaim.select('decided_by').maybeSingle();
     if (claimError || !claimed) {

package/build/lib/approval-chat-confirm.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const confirmApprovalInput: {
+    approval_id: z.ZodString;
+    action: z.ZodString;
+    echo: z.ZodString;
+    user_reply: z.ZodString;
+};
+declare const inputSchema: z.ZodObject<{
+    approval_id: z.ZodString;
+    action: z.ZodString;
+    echo: z.ZodString;
+    user_reply: z.ZodString;
+}, z.core.$strip>;
+export declare const CHAT_CONFIRM_NOT_ENABLED = "Chat confirm is not enabled for this connection. Use the on-screen prompt or approve_url.";
+/** This opt-in boundary is protected by the Claude Code PreToolUse hook, not elicitation. */
+export declare function confirmApproval(input: z.infer<typeof inputSchema>): Promise<{
+    code: string;
+    error: string;
+} | {
+    decision_status: 'approved';
+    approval_id: string;
+    next: string;
+}>;
+export {};

package/build/lib/approval-chat-confirm.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { buildApprovalPreview } from '@sendinel/domain';
+import { requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { humanApprovalEligible, chatConfirmConnectionEnabled } from './approval-human-eligibility.js';
+import { approvalStore } from './tester-requests-store.js';
+import { approvalPayloadHash } from './action-approvals.js';
+export const confirmApprovalInput = {
+    approval_id: z.string().uuid(),
+    action: z.string(),
+    echo: z.string().max(300),
+    user_reply: z.string().min(1).max(500),
+};
+const inputSchema = z.object(confirmApprovalInput);
+const refuse = (code, error, extra = {}) => ({ code, error, ...extra });
+export const CHAT_CONFIRM_NOT_ENABLED = 'Chat confirm is not enabled for this connection. Use the on-screen prompt or approve_url.';
+/** This opt-in boundary is protected by the Claude Code PreToolUse hook, not elicitation. */
+export async function confirmApproval(input) {
+    const actor = requestContext();
+    if (actor?.chatConfirmEnabled !== true)
+        return refuse('chat_confirm_not_enabled', CHAT_CONFIRM_NOT_ENABLED);
+    if (!inputSchema.safeParse(input).success)
+        return refuse('chat_confirm_invalid_input', 'Invalid confirm_approval arguments. user_reply must contain 1 to 500 characters and echo at most 300.');
+    const projectId = getProjectId();
+    if (!await humanApprovalEligible(input.action, projectId, actor)) {
+        return refuse('chat_confirm_ineligible', 'Chat confirm requires an enabled human OAuth connection and an owner/admin for admin actions.');
+    }
+    if (!await chatConfirmConnectionEnabled(actor))
+        return refuse('chat_confirm_not_enabled', CHAT_CONFIRM_NOT_ENABLED);
+    try {
+        const source = approvalStore();
+        const client = typeof source.schema === 'function' ? source.schema('email') : source;
+        const { data: approval, error: loadError } = await client.from('action_approvals')
+            .select('id, project_id, oauth_token_id, action, tier, status, used_at, requested_at, expires_at, params, summary, payload_hash')
+            .eq('id', input.approval_id).eq('project_id', projectId).eq('oauth_token_id', actor.oauthTokenId).maybeSingle();
+        if (loadError)
+            return refuse('chat_confirm_lookup_failed', 'Unable to verify the approval. Nothing was recorded.');
+        if (!approval || approval.project_id !== projectId || approval.oauth_token_id !== actor.oauthTokenId) {
+            return refuse('chat_confirm_not_found', 'Approval not found for this connection and project.');
+        }
+        if (approval.tier !== 'gated')
+            return refuse('chat_confirm_tier', 'Chat confirm supports gated approvals only. Protected actions require dashboard approval.');
+        if (approval.status !== 'pending' || approval.used_at != null)
+            return refuse('chat_confirm_not_pending', 'Approval is already decided or used. Request a new approval.');
+        const now = Date.now();
+        const requested = Date.parse(approval.requested_at);
+        if (!(Date.parse(approval.expires_at) > now))
+            return refuse('chat_confirm_expired', 'Approval has expired. Request a new approval, or tap the approve_url.');
+        if (!Number.isFinite(requested) || requested > now || requested < now - 600_000) {
+            return refuse('chat_confirm_too_old', 'Chat confirm requires an approval requested within the last 10 minutes. Request a new approval, or tap the approve_url.');
+        }
+        if (input.action !== approval.action)
+            return refuse('chat_confirm_action_mismatch', 'Action does not match the approval.');
+        if (!approval.params || approvalPayloadHash(approval.action, approval.params) !== approval.payload_hash) {
+            return refuse('chat_confirm_payload_changed', 'Approval payload could not be verified. Request a new approval.');
+        }
+        const { data: project, error: projectError } = await client.from('projects').select('name').eq('id', projectId).maybeSingle();
+        if (projectError || !project || typeof project.name !== 'string')
+            return refuse('chat_confirm_lookup_failed', 'Unable to verify the approval. Nothing was recorded.');
+        const echo = buildApprovalPreview({ action: approval.action, params: approval.params, summary: approval.summary,
+            projectName: project.name }).plain_summary.split('\n')[0].trim();
+        if (!echo || input.echo.trim() !== echo)
+            return refuse('chat_confirm_echo_mismatch', `Echo does not match the approval. Use this first line: ${echo}`, { echo });
+        // Re-check time and frozen bindings at the write, so replay/concurrent changes cannot win.
+        const decidedAt = new Date().toISOString();
+        const { data: decided, error: decisionError } = await client.from('action_approvals')
+            .update({ status: 'approved', decided_via: 'chat_confirm', decided_by: actor.actorId, decided_at: decidedAt })
+            .eq('id', input.approval_id).eq('project_id', projectId).eq('oauth_token_id', actor.oauthTokenId)
+            .eq('action', input.action).eq('tier', 'gated').eq('status', 'pending').is('used_at', null)
+            .gt('expires_at', decidedAt).eq('requested_at', approval.requested_at)
+            .gt('requested_at', new Date(Date.now() - 600_000 - 1).toISOString())
+            .eq('payload_hash', approval.payload_hash).eq('params', JSON.stringify(approval.params))
+            .select('id, payload_hash').maybeSingle();
+        if (decisionError || !decided)
+            return refuse('chat_confirm_not_pending', 'Approval is already decided, used or no longer valid. Request a new approval.');
+        const { error: auditError } = await client.from('audit_log').insert({
+            project_id: projectId, actor_type: 'user', actor_id: actor.actorId,
+            action: 'approval.submitted', resource_type: 'approval', resource_id: input.approval_id,
+            details: { status: 'approved', channel: 'chat_confirm', user_reply: input.user_reply.replace(/[\p{Cc}]/gu, '').slice(0, 500),
+                echo, payload_hash: decided.payload_hash, connection_id: `oauth:${actor.oauthTokenId}` },
+        });
+        if (auditError)
+            return refuse('chat_confirm_audit_failed', 'Approval recorded, but decision audit failed. Check approval status before retrying.');
+        return { decision_status: 'approved', approval_id: input.approval_id,
+            next: `Call ${input.action} again with the same arguments plus approval_id.` };
+    }
+    catch {
+        return refuse('chat_confirm_failed', 'Chat confirm failed. Check approval status before retrying.');
+    }
+}

package/build/lib/approval-human-eligibility.d.ts

@@ -4,10 +4,32 @@ export type HumanDecisionIdentity = {
     oauthTokenId?: string | null;
     authKind?: string | null;
     channelVerified?: boolean;
+    chatConfirmEnabled?: boolean;
     scopes?: readonly string[];
 };
 /** Shared transport boundary, never populated from tool arguments. Re-read the grant and
  * (for admin requests) the project's org membership on every prompt and every decision.
  * Missing connection_role is NOT a human grant: it must be exactly SQL NULL.
  */
-export declare function humanApprovalEligible(action: string, projectId: string, identity?: HumanDecisionIdentity | undefined): Promise<boolean>;
+export declare function humanApprovalEligible(action: string, projectId: string, identity?: HumanDecisionIdentity | undefined, requireChatConfirm?: boolean): Promise<boolean>;
+/** Opt-in is a live grant fact as well as a transport snapshot; errors never enable it. */
+export declare function chatConfirmConnectionEnabled(identity?: {
+    scopes?: readonly string[];
+    approvedTesterAction?: string;
+    projectId?: string;
+    approvalMode?: string;
+    channel?: string;
+    channelVerified?: boolean;
+    actorType?: string;
+    actorId?: string | null;
+    oauthTokenId?: string | null;
+    chatConfirmEnabled?: boolean;
+    invitationProjectIds?: string[] | null;
+    authKind?: string | null;
+    oauthClientId?: string | null;
+    agentLabel?: string | null;
+    keyId?: string | null;
+    workspaceId?: string | null;
+    kid?: string | null;
+    v1Caller?: import("../db.js").V1Caller;
+} | undefined): Promise<boolean>;

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

@@ -5,8 +5,9 @@ import { isHumanRequestableAdminTool } from './admin-tools.js';
  * (for admin requests) the project's org membership on every prompt and every decision.
  * Missing connection_role is NOT a human grant: it must be exactly SQL NULL.
  */
-export async function humanApprovalEligible(action, projectId, identity = requestContext()) {
+export async function humanApprovalEligible(action, projectId, identity = requestContext(), requireChatConfirm = false) {
     if (!identity || identity.channelVerified !== true || identity.authKind !== 'oauth' ||
+        (requireChatConfirm && identity.chatConfirmEnabled !== true) ||
         !identity.actorId || !identity.oauthTokenId || identity.projectId !== projectId || !projectId ||
         identity.scopes?.some(scope => scope === 'tester' || scope === 'agent'))
         return false;
@@ -14,10 +15,11 @@ export async function humanApprovalEligible(action, projectId, identity = reques
         const source = approvalStore();
         const client = typeof source.schema === 'function' ? source.schema('email') : source;
         const { data: grant, error } = await client.from('mcp_oauth_tokens')
-            .select('id, user_id, connection_role, scopes, revoked_at, expires_at')
+            .select('id, user_id, connection_role, scopes, revoked_at, expires_at, chat_confirm_enabled')
             .eq('id', identity.oauthTokenId).maybeSingle();
         if (error || !grant || grant.id !== identity.oauthTokenId || grant.user_id !== identity.actorId ||
             grant.connection_role !== null || grant.revoked_at !== null ||
+            (requireChatConfirm && grant.chat_confirm_enabled !== true) ||
             !(Date.parse(grant.expires_at) > Date.now()) || !Array.isArray(grant.scopes) ||
             grant.scopes.some((scope) => scope === 'tester' || scope === 'agent'))
             return false;
@@ -37,3 +39,18 @@ export async function humanApprovalEligible(action, projectId, identity = reques
         return false;
     }
 }
+/** Opt-in is a live grant fact as well as a transport snapshot; errors never enable it. */
+export async function chatConfirmConnectionEnabled(identity = requestContext()) {
+    if (identity?.chatConfirmEnabled !== true || !identity.oauthTokenId)
+        return false;
+    try {
+        const source = approvalStore();
+        const client = typeof source.schema === 'function' ? source.schema('email') : source;
+        const { data, error } = await client.from('mcp_oauth_tokens').select('chat_confirm_enabled')
+            .eq('id', identity.oauthTokenId).maybeSingle();
+        return !error && data?.chat_confirm_enabled === true;
+    }
+    catch {
+        return false;
+    }
+}

package/build/server.d.ts

@@ -4,6 +4,8 @@ export interface ToolRegistrationOptions {
     scopes?: string[];
     toolGroups?: string[];
     toolAllowlist?: string[];
+    /** Server-owned connection opt-in; undefined only for unrestricted registry collectors. */
+    chatConfirmEnabled?: boolean;
 }
 declare const GROUP_REGISTRY: Record<string, (server: McpServer, options?: ToolRegistrationOptions) => void>;
 export declare const ALL_TOOL_GROUPS: string[];

package/build/server.js

@@ -375,7 +375,7 @@ export function registerAllTools(server, options) {
     if (rawScopes.includes('gateway')) {
         const permissionScopes = rawScopes.filter((scope) => scope !== 'gateway');
         const proxied = createScopeProxy(server, permissionScopes, 'gateway');
-        registerGatewayTools(proxied, { scopes: permissionScopes, toolGroups: options?.toolGroups, toolAllowlist: options?.toolAllowlist });
+        registerGatewayTools(proxied, { scopes: permissionScopes, toolGroups: options?.toolGroups, toolAllowlist: options?.toolAllowlist, chatConfirmEnabled: options?.chatConfirmEnabled === true });
         return;
     }
     const groups = options?.toolGroups === undefined

package/build/tools/approvals.d.ts

@@ -1,2 +1,3 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerApprovalTools(server: McpServer): void;
+import type { ToolRegistrationOptions } from '../server.js';
+export declare function registerApprovalTools(server: McpServer, options?: ToolRegistrationOptions): void;

package/build/tools/approvals.js

@@ -2,9 +2,22 @@ import { z } from 'zod';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { checkApproval } from '../lib/action-approvals.js';
+import { confirmApproval, confirmApprovalInput } from '../lib/approval-chat-confirm.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
-export function registerApprovalTools(server) {
+export function registerApprovalTools(server, options) {
+    if (options?.chatConfirmEnabled !== false && (!options?.scopes || options.chatConfirmEnabled === true) &&
+        !options?.scopes?.some(scope => scope === 'tester' || scope === 'agent')) {
+        server.registerTool('confirm_approval', {
+            title: 'Confirm Approval',
+            description: "Records the user's yes. The user's own client shows a confirmation prompt. Never call this without asking the user first.",
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            inputSchema: confirmApprovalInput,
+        }, async (args) => {
+            const result = await confirmApproval(args);
+            return { ...j(result), ...('code' in result ? { isError: true } : {}) };
+        });
+    }
     server.registerTool('check_approval', {
         title: 'Check Approval',
         annotations: {

package/build/tools/gateway.d.ts

@@ -3,6 +3,7 @@ export interface GatewayOptions {
     scopes?: string[];
     toolGroups?: string[];
     toolAllowlist?: string[];
+    chatConfirmEnabled?: boolean;
 }
 /**
  * Plain words people use for a tool (#3669, #4059). The map lives in tool-search.ts so how_to can

package/build/tools/gateway.js

@@ -25,12 +25,12 @@ export function matchesToolQuery(entry, query) {
 const SEARCH_LIMIT = 10;
 async function buildCatalog(options) {
     const innerServer = new McpServer({ name: 'sendinel-gateway-inner', version: '1.0.0' });
-    registerAllTools(innerServer, { scopes: options.scopes, toolGroups: options.toolGroups, toolAllowlist: options.toolAllowlist });
+    registerAllTools(innerServer, { scopes: options.scopes, toolGroups: options.toolGroups, toolAllowlist: options.toolAllowlist, chatConfirmEnabled: options.chatConfirmEnabled === true });
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const client = new Client({ name: 'sendinel-gateway', version: '1.0.0' });
     await innerServer.connect(serverTransport);
     await client.connect(clientTransport);
-    const toolGroupMap = getRegisteredToolGroups({ scopes: options.scopes, toolGroups: options.toolGroups, toolAllowlist: options.toolAllowlist });
+    const toolGroupMap = getRegisteredToolGroups({ scopes: options.scopes, toolGroups: options.toolGroups, toolAllowlist: options.toolAllowlist, chatConfirmEnabled: options.chatConfirmEnabled === true });
     const { tools } = await client.listTools();
     const entries = tools
         .map((tool) => ({

package/package.json

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