@sendinel/mcp-server 1.0.143 → 1.0.145

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 344 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 346 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 344 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` | 3 | Poll and list risk-tiered action approvals |
+| `approvals` | 5 | Poll/list approvals, person OAuth approval, write-scoped cancellation, opted-in chat confirmation |
 | `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 |
@@ -58,6 +58,14 @@ Sendinel currently exposes 35 tool groups and 344 tools (gateway mode exposes 4
 | `warmup` | 4 | IP/domain warmup schedule control |
 | `webhooks` | 5 | Webhook subscription management |
 
+`cancel_approval({approval_id})` rejects an unexpired, unused pending/approved
+request in the current project for any write-scoped credential.
+`approve_approval({approval_id})` requires the person's own live OAuth connection
+(`connection_role: NULL`) and its own pending request in that project. Tester,
+agent, API key, service-token and scoped-JWT credentials cannot approve. Sends
+and deletes still need approval; the user may answer through their AI without
+another verification prompt. See [approval tools](../../docs/mcp-tools.md#approve_approval).
+
 ## Install / run
 
 ```bash

package/build/lib/action-approvals.js

@@ -405,10 +405,10 @@ 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' &&
+    // Tool decisions stay bound to the same live human grant at consumption, for every action.
+    if (data.status === 'approved' && ['chat_confirm', 'mcp_person'].includes(data.decided_via) &&
         (requestContext()?.oauthTokenId !== data.oauth_token_id || requestContext()?.actorId !== data.decided_by ||
-            !await humanApprovalEligible(data.action, getProjectId(), requestContext(), true))) {
+            !await humanApprovalEligible(data.action, getProjectId(), requestContext(), data.decided_via === 'chat_confirm'))) {
         return { approved: false, status: 'human_decision_required' };
     }
     const sandboxDecision = data.decided_via === 'sandbox';
@@ -418,7 +418,7 @@ export async function checkApproval(approvalId, options = {}) {
     }
     if (data.status === 'approved' && !sandboxDecision && (!isHumanApprovalChannel(data.decided_via) ||
         (isHumanRequestableAdminTool(data.action) && data.decided_via !== 'dashboard' &&
-            (!['mcp_app', 'mcp_elicitation', 'chat_confirm'].includes(data.decided_via) ||
+            (!['mcp_app', 'mcp_elicitation', 'chat_confirm', 'mcp_person'].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' };
@@ -459,7 +459,7 @@ 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')
+    if (['chat_confirm', 'mcp_person'].includes(data.decided_via))
         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();

package/build/lib/approval-exempt.js

@@ -20,8 +20,10 @@ export const APPROVAL_EXEMPT = {
     add_suppression: "only stops mail to an address; reduces sending",
     add_synced_folder: "starts syncing a Drive folder into the project own media library; inbound only",
     add_white_label_domain: "adds a pending branding domain record; reversible and sends nothing",
+    approve_approval: "is the approval step itself: only a person-role OAuth connection can decide its own pending request, bound to that token and project, audited; sends nothing",
     approve_data_proposal: "turns a proposal into an AI draft for review; sends nothing",
     approve_draft: "marks a draft ready; sending still requires a gated send or activation",
+    cancel_approval: "only moves an unused approval to rejected (never grants anything); reduces what can run",
     cancel_send_queue_rows: "cancels queued mail before it sends; reduces sending",
     clone_campaign: "creates a draft copy of a campaign; nothing sends until activated (gated)",
     clone_sequence_template: "creates a draft campaign from a template; nothing sends until activated (gated)",

package/build/lib/approval-tool-decisions.d.ts

@@ -0,0 +1,15 @@
+export declare function cancelApproval(approvalId: string, transportClientName?: string): Promise<{
+    code: string;
+    error: string;
+} | {
+    approval_id: string;
+    status: 'rejected';
+}>;
+export declare function approveApproval(approvalId: string, transportClientName?: string): Promise<{
+    code: string;
+    error: string;
+} | {
+    approval_id: string;
+    decision_status: 'approved';
+    next: string;
+}>;

package/build/lib/approval-tool-decisions.js

@@ -0,0 +1,103 @@
+import { requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { humanApprovalEligible } from './approval-human-eligibility.js';
+import { approvalStore } from './tester-requests-store.js';
+const refuse = (code, error) => ({ code, error });
+const store = () => approvalStore().schema('email');
+/** OAuth names come from the registered client, never a model-supplied argument. */
+async function clientName(fallback) {
+    const actor = requestContext();
+    if (!actor?.oauthTokenId)
+        return fallback ?? actor?.agentLabel ?? null;
+    const client = store();
+    const { data: grant, error: grantError } = await client.from('mcp_oauth_tokens')
+        .select('client_id').eq('id', actor.oauthTokenId).maybeSingle();
+    if (grantError || !grant?.client_id)
+        throw new Error('Unable to identify the OAuth client');
+    const { data, error } = await client.from('mcp_oauth_clients')
+        .select('client_name').eq('client_id', grant.client_id).maybeSingle();
+    if (error || typeof data?.client_name !== 'string')
+        throw new Error('Unable to identify the OAuth client');
+    return data.client_name;
+}
+export async function cancelApproval(approvalId, transportClientName) {
+    const actor = requestContext();
+    if (!actor?.scopes?.some(scope => scope === 'write' || scope === 'admin')) {
+        return refuse('approval_forbidden', 'Cancelling an approval requires write scope.');
+    }
+    try {
+        const projectId = getProjectId();
+        const name = await clientName(transportClientName);
+        const now = new Date().toISOString();
+        // A single conditional write arbitrates cancellation versus approval/consumption.
+        // Preserve the original decision provenance; cancellation never grants authority.
+        const { data, error } = await store().from('action_approvals')
+            .update({ status: 'rejected' })
+            .eq('id', approvalId).eq('project_id', projectId)
+            .in('status', ['pending', 'approved']).is('used_at', null).gt('expires_at', now)
+            .select('id').maybeSingle();
+        if (error)
+            return refuse('approval_update_failed', 'Unable to cancel the approval. Check its status before retrying.');
+        if (!data)
+            return refuse('approval_not_cancellable', 'No unexpired, unused pending or approved approval found in this project.');
+        const { error: auditError } = await store().from('audit_log').insert({
+            project_id: projectId, actor_type: actor.actorType ?? actor.authKind ?? 'api_key',
+            actor_id: actor.actorId ?? actor.keyId ?? actor.oauthTokenId ?? null,
+            action: 'approval.cancelled', resource_type: 'approval', resource_id: approvalId,
+            details: { status: 'rejected', client_name: name, auth_kind: actor.authKind ?? null,
+                oauth_token_id: actor.oauthTokenId ?? null, api_key_id: actor.keyId ?? null },
+        });
+        if (auditError)
+            return refuse('approval_audit_failed', 'Approval cancelled, but audit failed. Check its status before retrying.');
+        return { approval_id: approvalId, status: 'rejected' };
+    }
+    catch {
+        return refuse('approval_failed', 'Cancellation failed. Check approval status before retrying.');
+    }
+}
+export async function approveApproval(approvalId, transportClientName) {
+    const actor = requestContext();
+    const projectId = getProjectId();
+    // Reuse the same live-grant identification as the app/elicitation path (#4312).
+    if (!await humanApprovalEligible('approve_approval', projectId, actor)) {
+        return refuse('approval_forbidden', 'Approval requires your own verified person-role OAuth connection in this project.');
+    }
+    try {
+        const client = store();
+        const { data: approval, error: loadError } = await client.from('action_approvals')
+            .select('action, params, payload_hash')
+            .eq('id', approvalId).eq('project_id', projectId).eq('oauth_token_id', actor.oauthTokenId)
+            .eq('status', 'pending').is('used_at', null).gt('expires_at', new Date().toISOString()).maybeSingle();
+        if (loadError)
+            return refuse('approval_lookup_failed', 'Unable to verify the approval. Nothing was recorded.');
+        if (!approval)
+            return refuse('approval_not_pending', 'No unexpired, unused pending approval found for this connection and project.');
+        if (!await humanApprovalEligible(approval.action, projectId, actor)) {
+            return refuse('approval_forbidden', 'This approval requires a person with the required project role.');
+        }
+        const name = await clientName(transportClientName);
+        const now = new Date().toISOString();
+        const decision = client.from('action_approvals')
+            .update({ status: 'approved', decided_via: 'mcp_person', decided_by: actor.actorId, decided_at: now })
+            .eq('id', approvalId).eq('project_id', projectId).eq('oauth_token_id', actor.oauthTokenId)
+            .eq('action', approval.action).eq('status', 'pending').is('used_at', null).gt('expires_at', now)
+            .eq('params', JSON.stringify(approval.params));
+        const bound = approval.payload_hash == null ? decision.is('payload_hash', null) : decision.eq('payload_hash', approval.payload_hash);
+        const { data, error } = await bound.select('id, payload_hash').maybeSingle();
+        if (error || !data)
+            return refuse('approval_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: approvalId,
+            details: { status: 'approved', channel: 'mcp_person', client_name: name,
+                connection_id: `oauth:${actor.oauthTokenId}`, payload_hash: data.payload_hash },
+        });
+        if (auditError)
+            return refuse('approval_audit_failed', 'Approval recorded, but audit failed. Check its status before retrying.');
+        return { approval_id: approvalId, decision_status: 'approved',
+            next: `Call ${approval.action} again with the same arguments plus approval_id.` };
+    }
+    catch {
+        return refuse('approval_failed', 'Approval failed. Check approval status before retrying.');
+    }
+}

package/build/server.js

@@ -87,6 +87,7 @@ export const ALL_TOOL_GROUPS = Object.keys(GROUP_REGISTRY);
 // ── Scope enforcement ─────────────────────────────────────────────────────
 // Maps tool names to required scope. Mirrors dashboard's WRITE_TOOLS/ADMIN_TOOLS.
 const WRITE_TOOLS = new Set([
+    'cancel_approval', 'approve_approval',
     'recheck_domain_dns',
     'mark_agent_message', 'draft_agent_reply', 'create_agent_mailbox',
     'add_subscriber', 'identify_subscriber', 'emit_contact_event', 'import_subscribers', 'update_subscriber', 'bulk_update_subscribers',
@@ -172,7 +173,7 @@ export function isAgentConnection(scopes) {
     return !!scopes?.includes(AGENT_CONNECTION_SCOPE);
 }
 export function agentConnectionAllowsTool(name) {
-    return ['list_agent_inbox', 'read_agent_message', 'get_agent_thread', 'mark_agent_message',
+    return ['cancel_approval', 'list_agent_inbox', 'read_agent_message', 'get_agent_thread', 'mark_agent_message',
         'draft_agent_reply', 'search_tools', 'describe_tool', 'invoke_tool'].includes(name);
 }
 export function agentConnectionRefusal(name) {
@@ -186,6 +187,7 @@ export function testerConnectionAllowsTool(name) {
     // Retain the existing campaign activation path. A globally gated tool is not by itself
     // permission for a tester: sends, deletes and access/infrastructure writes stay refused.
     return getRequiredScope(name) === 'read'
+        || name === 'cancel_approval'
         || TESTER_REQUEST_TOOLS.has(name)
         || name === 'activate_campaigns'
         || name === 'update_campaign_status';
@@ -321,7 +323,7 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                         const required = getRequiredScope(name);
                         const tester = isTesterConnection(scopes);
                         const agent = isAgentConnection(scopes);
-                        const allowed = () => agent ? agentConnectionAllowsTool(name) : tester
+                        const allowed = () => name === 'cancel_approval' ? scopeAllows(scopes, 'write') : agent ? agentConnectionAllowsTool(name) : tester
                             ? testerConnectionAllowsTool(name)
                             : scopeAllows(scopes, required) || (scopeAllows(scopes, 'read') && isHumanRequestableAdminTool(name));
                         if (!allowed()) {

package/build/tools/approvals.js

@@ -4,9 +4,29 @@ 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';
+import { approveApproval, cancelApproval } from '../lib/approval-tool-decisions.js';
+import { approvalClientName } from '../lib/approval-capabilities.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 export function registerApprovalTools(server, options) {
+    server.registerTool('cancel_approval', {
+        title: 'Cancel Approval',
+        description: 'Cancel an unexpired, unused pending or approved action approval in this project. Requires write scope. Sets it to rejected; cannot approve or undo cancellation.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: { approval_id: z.string().uuid() },
+    }, async ({ approval_id }) => {
+        const result = await cancelApproval(approval_id, server.server && approvalClientName(server.server));
+        return { ...j(result), ...('code' in result ? { isError: true } : {}) };
+    });
+    server.registerTool('approve_approval', {
+        title: 'Approve Approval',
+        description: "Record the person's approval through their own OAuth connection for this project. Only person-role OAuth connections may approve their own pending, unexpired, unused requests. Tester, agent, API key, service token and scoped JWT credentials cannot approve. Call only when the person asks to approve; then retry the original action with approval_id.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: { approval_id: z.string().uuid() },
+    }, async ({ approval_id }) => {
+        const result = await approveApproval(approval_id, server.server && approvalClientName(server.server));
+        return { ...j(result), ...('code' in result ? { isError: true } : {}) };
+    });
     if (options?.chatConfirmEnabled !== false && (!options?.scopes || options.chatConfirmEnabled === true) &&
         !options?.scopes?.some(scope => scope === 'tester' || scope === 'agent')) {
         server.registerTool('confirm_approval', {

package/build/tools/campaigns.js

@@ -92,7 +92,11 @@ export function buildCampaignFiresOn(campaign) {
         parts.push(`event${events.length > 1 ? 's' : ''} ${events.map((e) => `"${e}"`).join(', ')} sent to /v1/events`);
     if (tags.length)
         parts.push(`tag${tags.length > 1 ? 's' : ''} ${tags.map((t) => `"${t}"`).join(', ')} added`);
-    if (campaign.segment_id)
+    if (campaign.type === 'broadcast') {
+        parts.length = 0;
+        parts.push(campaign.send_at ? `the scheduled send time (${campaign.send_at})` : 'nothing scheduled (no send_at set)');
+    }
+    else if (campaign.segment_id)
         parts.push('contacts entering its segment');
     let summary = parts.length ? `Fires on: ${parts.join('; ')}.` : 'Fires on: nothing (no trigger set).';
     const warnings = [];
@@ -731,7 +735,7 @@ export function registerCampaignTools(server) {
     }, async ({ site_id, status, limit, period }) => {
         let q = db()
             .from('campaigns')
-            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config, send_class, unsub_footer_template, requires_approval, approved_by, approved_at')
+            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config, send_class, unsub_footer_template, requires_approval, approved_by, approved_at, send_at')
             .eq('project_id', getProjectId())
             .order('created_at', { ascending: false })
             .limit(limit ?? 25);
@@ -2956,14 +2960,16 @@ Do not include body_html in your response; Sendinel renders body_html from block
     }, async ({ html, site_id, custom_variables, subject, body_text, trigger_event_name, event_keys }) => {
         const projectId = getProjectId();
         let voiceConfig = null;
+        let autoUnsubscribeFooter = true;
         if (site_id) {
             const { data: site } = await db()
                 .from('sites')
-                .select('brand_voice')
+                .select('brand_voice, unsub_link_enabled')
                 .eq('id', site_id)
                 .eq('project_id', projectId)
                 .maybeSingle();
             voiceConfig = site?.brand_voice ?? null;
+            autoUnsubscribeFooter = site?.unsub_link_enabled !== false;
         }
         // The brand kit's sign-off name applies to every site in the project (#3854).
         const { data: projectRow } = await db().from('projects').select('brand_settings').eq('id', projectId).maybeSingle();
@@ -2973,16 +2979,19 @@ Do not include body_html in your response; Sendinel renders body_html from block
             .filter((row) => !site_id || row.id === site_id)
             .flatMap((row) => [sendingHostOf(row.sending_domain), sendingHostOf(row.from_email)])
             .filter((host) => Boolean(host));
+        const contacts = await contactPropertyKeys(projectId);
+        const { data: definitions } = await db().from('custom_field_definitions').select('key').eq('project_id', projectId);
+        const contactVariables = [...(contacts?.keys ?? []), ...(definitions ?? []).map((field) => field.key)].map((key) => `custom.${key}`);
         let sourcedKeys;
         if (trigger_event_name || event_keys) {
             const fromHistory = trigger_event_name ? await eventKeysFromHistory(projectId, trigger_event_name) : [];
-            const contacts = await contactPropertyKeys(projectId);
             sourcedKeys = fromHistory === null || contacts === null
                 ? null
-                : [...(event_keys ?? []), ...fromHistory, ...contacts.keys.map((key) => `custom.${key}`)];
+                : [...(event_keys ?? []), ...fromHistory, ...contactVariables];
         }
         const result = validateTemplate(html, voiceConfig, {
-            customVariables: [...(custom_variables ?? []), ...(sourcedKeys ?? [])],
+            customVariables: [...(custom_variables ?? []), ...contactVariables, ...(sourcedKeys ?? [])],
+            autoUnsubscribeFooter,
             subject,
             bodyText: body_text,
             brandSettings: projectRow?.brand_settings ?? null,
@@ -3004,7 +3013,7 @@ Do not include body_html in your response; Sendinel renders body_html from block
             else if (!result.errors.some((error) => error.includes(issue.excerpt)))
                 result.warnings.push(issue.message);
         }
-        return j({ ...result, valid: result.errors.length === 0 });
+        return j({ ...result, valid: result.errors.length === 0, ...(result.errors.length ? { code: 'validation_failed' } : {}) });
     });
     server.registerTool('check_content_consistency', {
         title: 'Check Content Consistency',

package/build/tools/contacts.js

@@ -493,8 +493,8 @@ function primaryContactValue(value) {
 }
 // #3623: last_transactional_at / total_transactional_sent are service (transactional) mail, tracked apart
 // from the marketing last_emailed_at / total_emails_sent. NULL means none recorded, not "never".
-const SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage';
-const SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage';
+const SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage, tags';
+const SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, global_unsubscribed, source, created_at, last_emailed_at, total_emails_sent, last_transactional_at, total_transactional_sent, total_opens, total_clicks, engagement_score, lifecycle_stage, tags';
 const SEGMENT_SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_opens, total_clicks';
 const SEGMENT_SUBSCRIBER_SELECT_NO_COMPANY = 'id, email, first_name, last_name, company_id, engagement_score, lifecycle_stage, last_opened_at, last_clicked_at, total_opens, total_clicks';
 const UPDATE_SUBSCRIBER_SELECT_WITH_COMPANY = 'id, email, first_name, last_name, company_id, company:companies(id, name, domain), custom_properties, tags, phone_e164, timezone';
@@ -962,7 +962,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List contacts, optionally filtered by site, search term, and/or a saved subscriber view. Explicit arguments and saved-view filters are combined to narrow the result.',
+        description: 'List contacts including tags, optionally filtered by site, search term, and/or a saved subscriber view. Explicit arguments and saved-view filters are combined to narrow the result.',
         inputSchema: {
             site_id: z.string().uuid().optional(),
             company_id: z.string().uuid().optional(),

package/build/tools/gateway.js

@@ -7,9 +7,9 @@ import { getRegisteredToolGroups, registerAllTools } from '../server.js';
 import { rankTools, scoreTool, TOOL_ALIASES, tokenize } from './tool-search.js';
 const textResult = (text) => ({ content: [{ type: 'text', text }] });
 const jsonResult = (data) => textResult(JSON.stringify(data, null, 2));
-const notFound = (message) => ({
+const notFound = (message, code = 'not_found') => ({
     isError: true,
-    content: [{ type: 'text', text: message }],
+    ...jsonResult({ error: message, code }),
 });
 /**
  * Plain words people use for a tool (#3669, #4059). The map lives in tool-search.ts so how_to can
@@ -49,7 +49,7 @@ async function buildCatalog(options) {
 function unknownKeyMessage(keys) {
     const list = keys.map((k) => `'${k}'`).join(', ');
     const hinted = keys.some((k) => ARGS_LOOKALIKES.has(k.toLowerCase()));
-    return `Unknown key(s) on invoke_tool: ${list}${hinted ? "; did you mean 'args'?" : ''} Valid keys: name, args (alias: arguments).`;
+    return `Unknown key(s) on invoke_tool: ${list}${hinted ? "; did you mean 'args'?" : ''} Valid keys: name, args (alias: arguments), project_id.`;
 }
 const ARGS_LOOKALIKES = new Set(['args', 'argument', 'params', 'input', 'parameters']);
 function declaredProperties(inputSchema) {
@@ -83,20 +83,28 @@ export function registerGatewayTools(server, options) {
     const getCatalog = () => (catalogPromise ??= buildCatalog(options));
     server.registerTool('search_tools', {
         title: 'Search Tools',
-        description: 'Search the permitted Sendinel MCP tool catalog by keyword and/or group. Returns name, group, and description. Call describe_tool for the full input schema before invoke_tool.',
+        description: 'Search the permitted Sendinel MCP tool catalog by keyword and/or group. Returns name, group, and description. Optional limit/offset page ranked search results or explicit browsing. Call describe_tool for the full input schema before invoke_tool.',
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             query: z.string().optional().describe('Words to match against tool name, group, description, or common phrasing (for example "send email")'),
             group: z.string().optional().describe('Restrict results to one tool group, for example campaigns'),
+            limit: z.number().int().min(1).max(50).optional().describe('Page size (1–50); ranked search defaults to 10, browsing stays uncapped unless paging is supplied'),
+            offset: z.number().int().min(0).optional().describe('Zero-based result offset (default 0)'),
         },
-    }, async ({ query, group }) => {
+    }, async ({ query, group, limit, offset }) => {
         const catalog = await getCatalog();
         const q = query?.trim().toLowerCase() ?? '';
         const requestedGroup = group?.trim();
         const scoped = catalog.entries.filter((tool) => !requestedGroup || tool.group === requestedGroup);
         const summarize = ({ name, group, description }) => ({ name, group, description });
+        const start = offset ?? 0;
+        const pageSize = limit ?? SEARCH_LIMIT;
         if (!q) {
-            return jsonResult({ tools: scoped.map(summarize), total: scoped.length });
+            if (limit === undefined && offset === undefined)
+                return jsonResult({ tools: scoped.map(summarize), total: scoped.length });
+            const page = scoped.slice(start, start + pageSize);
+            const truncated = start + page.length < scoped.length;
+            return jsonResult({ tools: page.map(summarize), total: scoped.length, truncated, ...(truncated ? { next_offset: start + page.length } : {}) });
         }
         const { matches, nearest } = rankTools(scoped, q);
         if (matches.length === 0) {
@@ -108,12 +116,14 @@ export function registerGatewayTools(server, options) {
                 hint: 'No tool matched that phrasing. The nearest tools are listed; try a shorter keyword, or browse with the group filter.',
             });
         }
-        const top = matches.slice(0, SEARCH_LIMIT);
+        const top = matches.slice(start, start + pageSize);
+        const truncated = start + top.length < matches.length;
         return jsonResult({
             tools: top.map(({ entry }) => summarize(entry)),
             total: matches.length,
             ranked: true,
-            ...(matches.length > top.length ? { truncated: true } : {}),
+            truncated,
+            ...(truncated ? { next_offset: start + top.length } : {}),
         });
     });
     server.registerTool('describe_tool', {
@@ -139,15 +149,16 @@ export function registerGatewayTools(server, options) {
             name: z.string().min(1).describe('Tool name to invoke'),
             args: z.record(z.string(), z.unknown()).optional().describe('Arguments for the target tool'),
             arguments: z.record(z.string(), z.unknown()).optional().describe('Alias for args (the MCP-standard field name). Provide args or arguments, not both.'),
+            project_id: z.string().uuid().optional().describe('Per-call project override, same as on any tool. The hosted transport selects and strips it before invocation; direct stdio calls use the configured project.'),
         }),
     }, async (input) => {
-        const { name, args, arguments: argumentsAlias, ...rest } = input;
+        const { name, args, arguments: argumentsAlias, project_id: _projectId, ...rest } = input;
         const unknownKeys = Object.keys(rest);
         if (unknownKeys.length > 0) {
-            return notFound(unknownKeyMessage(unknownKeys));
+            return notFound(unknownKeyMessage(unknownKeys), 'validation_failed');
         }
         if (args !== undefined && argumentsAlias !== undefined && JSON.stringify(args) !== JSON.stringify(argumentsAlias)) {
-            return notFound("Both 'args' and 'arguments' were provided with different values. Provide either 'args' or 'arguments', not both.");
+            return notFound("Both 'args' and 'arguments' were provided with different values. Provide either 'args' or 'arguments', not both.", 'validation_failed');
         }
         const effective = args ?? argumentsAlias ?? {};
         const catalog = await getCatalog();
@@ -157,7 +168,7 @@ export function registerGatewayTools(server, options) {
         }
         const unknownArgs = findUnknownArgKeys(entry.inputSchema, effective);
         if (unknownArgs.length > 0) {
-            return notFound(unknownArgsMessage(name, entry.inputSchema, unknownArgs));
+            return notFound(unknownArgsMessage(name, entry.inputSchema, unknownArgs), 'validation_failed');
         }
         return await catalog.client.callTool({ name, arguments: effective });
     });

package/build/tools/segments.js

@@ -297,7 +297,7 @@ export function registerSegmentTools(server) {
             model: getAnthropicModelId(),
             max_tokens: AI_MAX_TOKENS,
             ...outputConfig("low"),
-            system: 'You translate natural language audience descriptions into a JSON segment rule tree. Return ONLY valid JSON. Format: {"op":"AND"|"OR","conditions":[conditionOrGroup],"exclude_suppressed":true}. Condition format: {"field": string, "operator":"eq|neq|gt|gte|lt|lte|contains|exists|not_exists|after|before|on_or_after|on_or_before","value": any}. Supported fields: lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.plan, payment.mrr_cents, payment.ltv_cents, payment.subscription_status, payment.trial_ends_at, payment.churned_at, payment.paid_at, email_sends. email_sends uses eq only and value {"min_count":4,"within_days":30}; both required, at most one per segment. It counts email_log rows with non-null sent_at in the inclusive elapsed-day window through now, regardless of current status. No observed sends = zero; failed history reads are errors. Example: {"op":"AND","conditions":[{"field":"lifecycle_stage","operator":"eq","value":"trial"},{"field":"payment.trial_ends_at","operator":"on_or_before","value":"' + new Date(Date.now() + 7 * 86400000).toISOString() + '"}]}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
+            system: 'You translate natural language audience descriptions into a JSON segment rule tree. Return ONLY valid JSON. Format: {"op":"AND"|"OR","conditions":[conditionOrGroup],"exclude_suppressed":true}. Condition format: {"field": string, "operator":"eq|neq|gt|gte|lt|lte|contains|exists|not_exists|after|before|on_or_after|on_or_before","value": any}. Supported fields: lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.plan, payment.mrr_cents, payment.ltv_cents, payment.subscription_status, payment.trial_ends_at, payment.churned_at, payment.paid_at, email_sends. email_sends uses eq only and value {"min_count":4,"within_days":30}; both required, at most one per segment. It counts email_log rows with non-null sent_at in the inclusive elapsed-day window through now, regardless of current status. No observed sends = zero; failed history reads are errors. "tagged A and B AND never opened" means {"op":"AND","conditions":[{"field":"tags","operator":"contains","value":"A"},{"field":"tags","operator":"contains","value":"B"},{"field":"last_opened_at","operator":"not_exists"}],"exclude_suppressed":true}. Use one tags contains condition per required tag; never opened means last_opened_at not_exists (no value), not an unsupported activity field. Example: {"op":"AND","conditions":[{"field":"lifecycle_stage","operator":"eq","value":"trial"},{"field":"payment.trial_ends_at","operator":"on_or_before","value":"' + new Date(Date.now() + 7 * 86400000).toISOString() + '"}]}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
             messages: [{ role: 'user', content: description }],
         });
         const raw = anthropicCheckedText(resp);
@@ -308,8 +308,8 @@ export function registerSegmentTools(server) {
         catch (parseError) {
             // #4270: parsed rules that are missing or malformed are an error, never "everyone".
             if (isSegmentRulesError(parseError))
-                return txt(`Error: Could not use the rules parsed from "${description}". ${parseError.message}`);
-            return txt(`Error: Failed to parse rules from "${description}"`);
+                return toolError({ error: `Could not use the rules parsed from "${description}". ${parseError.message}`, code: 'validation_failed' });
+            return toolError({ error: `Failed to parse rules from "${description}"`, code: 'validation_failed' });
         }
         const ids = await getSegmentContactIds(parsedRules);
         const sample = ids.slice(0, 5);

package/package.json

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