npm - @sendinel/mcp-server - Versions diffs - 1.0.105 → 1.0.107 - Mend

@sendinel/mcp-server 1.0.105 → 1.0.107

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/build/approval-app-html.d.ts +2 -0
package/build/approval-app-html.js +124 -0
package/build/auth.js +1 -0
package/build/index.js +7 -1
package/build/lib/action-approvals.d.ts +1 -0
package/build/lib/action-approvals.js +6 -2
package/build/lib/approval-app-conventions.d.ts +25 -0
package/build/lib/approval-app-conventions.js +24 -0
package/build/lib/approval-app.d.ts +43 -0
package/build/lib/approval-app.js +161 -0
package/build/lib/approval-elicitation.d.ts +46 -0
package/build/lib/approval-elicitation.js +116 -0
package/build/server.js +5 -2
package/package.json +1 -1

package/build/approval-app-html.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ /** Single-file, network-free Apps UI; email images load only inside scriptless srcdoc. */
2	+ export declare const APPROVAL_APP_HTML: string;

package/build/approval-app-html.js ADDED Viewed

@@ -0,0 +1,124 @@
+/** Single-file, network-free Apps UI; email images load only inside scriptless srcdoc. */
+export const APPROVAL_APP_HTML = String.raw `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'nonce-__NONCE__'; style-src 'unsafe-inline'; img-src https: data:; frame-src 'self'; connect-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Review email approval</title>
+<style>body{font:15px system-ui,sans-serif;margin:16px;color:#17212b;background:white}pre{white-space:pre-wrap;overflow-wrap:anywhere}section{margin:20px 0}dt{font-weight:650}dd{margin:0 0 10px;white-space:pre-wrap;overflow-wrap:anywhere}.devices{display:flex;gap:16px;overflow:auto}iframe{height:480px;border:1px solid #ccd3db;background:white;flex:none}button{padding:12px 24px;margin:8px 8px 8px 0;border:1px solid #667;border-radius:6px;background:white;color:#17212b}#approve{background:#0c857a;color:white}button:disabled{opacity:.5}#status{white-space:pre-wrap}</style>
+</head><body><h1>Review email</h1><p id="status" role="status">Connecting to approval host…</p>
+<main id="preview"></main><button id="approve" disabled>Approve</button><button id="reject" disabled>Reject</button>
+<script id="approval-data" type="application/json" nonce="__NONCE__">__APP_DATA__</script>
+<script nonce="__NONCE__">
+(() => {
+  'use strict';
+  let data = JSON.parse(document.getElementById('approval-data').textContent);
+  let ready = false, started = false, serial = 0;
+  const pending = new Map();
+  const status = document.getElementById('status');
+  const buttons = [document.getElementById('approve'), document.getElementById('reject')];
+  const notify = (method, params) => parent.postMessage({jsonrpc:'2.0',method,params}, '*');
+  function request(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = ++serial;
+      const timeout = setTimeout(() => { pending.delete(id); reject(new Error('Host did not respond; open the dashboard approval link.')); }, 15000);
+      pending.set(id, {resolve, reject, timeout});
+      parent.postMessage({jsonrpc:'2.0',id,method,params}, '*');
+    });
+  }
+  function text(tag, value, target) {
+    const node = document.createElement(tag); node.textContent = String(value ?? 'unknown'); target.append(node); return node;
+  }
+  function safeEmail(html) {
+    // Parse inertly, then allow only email layout/formatting. No active elements,
+    // forms, navigation, event handlers, SVG/MathML, external CSS or arbitrary URLs.
+    const template = document.createElement('template'); template.innerHTML = html;
+    const tags = new Set('HTML HEAD BODY TITLE STYLE A B BLOCKQUOTE BR CENTER DIV EM FONT H1 H2 H3 H4 H5 H6 HR IMG LI OL P SMALL SPAN STRONG SUB SUP TABLE TBODY TD TFOOT TH THEAD TR U UL'.split(' '));
+    const attrs = new Set('style class id title alt width height align valign bgcolor border cellpadding cellspacing colspan rowspan role color face size'.split(' '));
+    for (const el of [...template.content.querySelectorAll('*')]) {
+      if (!tags.has(el.tagName) || el.namespaceURI !== 'http://www.w3.org/1999/xhtml') { el.remove(); continue; }
+      for (const attr of [...el.attributes]) {
+        if (el.tagName === 'IMG' && attr.name === 'src' && (/^https:\/\//i.test(attr.value) || /^data:image\/(png|gif|jpeg|webp);base64,/i.test(attr.value))) continue;
+        if (!attrs.has(attr.name)) el.removeAttribute(attr.name);
+      }
+    }
+    // CSP precedes every email element. The empty sandbox independently forbids
+    // scripts, same-origin access, top navigation, forms, popups and downloads.
+    const csp = document.createElement('meta'); csp.httpEquiv = 'Content-Security-Policy';
+    csp.content = "default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; img-src https: data:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+    return '<!doctype html><html><head>' + csp.outerHTML + '</head><body>' + template.innerHTML + '</body></html>';
+  }
+  function render() {
+    const root = document.getElementById('preview'); root.replaceChildren();
+    if (!data.preview) return;
+    const p = data.preview;
+    text('pre', p.plain_summary, root);
+    const dl = document.createElement('dl'); root.append(dl);
+    for (const [label,value] of [['From',p.sender],['Subject',p.subject],['Preheader',p.preheader || '(none)'],['Recipients',p.recipient_count == null ? 'unknown' : p.recipient_count],['Footer',p.footer_text || 'unknown']]) {
+      text('dt',label,dl); text('dd',value,dl);
+    }
+    for (const change of data.diff || []) {
+      const section = document.createElement('section'); root.append(section);
+      text('h2',change.field + ' — before → after',section);
+      text('pre',change.before + '\n→\n' + change.after,section);
+    }
+    for (const group of p.groups) {
+      text('h2',group.title,root); if (group.trigger) text('p',group.trigger,root);
+      for (const email of group.emails) {
+        const section = document.createElement('section'); root.append(section);
+        text('h3',email.label + ': ' + email.subject,section);
+        text('p','From: ' + email.from + '\nPreheader: ' + (email.preheader || '(none)'),section);
+        if (email.delay) text('p',email.delay,section);
+        const devices = document.createElement('div'); devices.className = 'devices'; section.append(devices);
+        for (const width of [600,375]) {
+          const device = document.createElement('div'); devices.append(device); text('p',width + 'px',device);
+          const frame = document.createElement('iframe'); frame.setAttribute('sandbox',''); frame.setAttribute('referrerpolicy','no-referrer');
+          frame.title = email.label + ' ' + width + 'px'; frame.width = String(width); frame.srcdoc = safeEmail(email.html || '<pre>' + email.text.replace(/&/g,'&amp;').replace(/</g,'&lt;') + '</pre>'); device.append(frame);
+        }
+      }
+    }
+    text('p','Template content shown; recipient merge fields resolve when sending. Expires: ' + data.expires_at,root);
+    text('p','Payload SHA-256: ' + data.payload_hash,root);
+    buttons.forEach(b => b.disabled = !ready || !data.app_session || started);
+  }
+  async function loadApproval(uri) {
+    const result = await request('resources/read',{uri});
+    const resource = new DOMParser().parseFromString(result.contents[0].text,'text/html');
+    const loaded = JSON.parse(resource.getElementById('approval-data').textContent);
+    // Host-only resource metadata, omitted from model-readable resource text.
+    loaded.app_session = result.contents[0]._meta?.[data.sessionMetaKey];
+    data = loaded; render(); status.textContent = data.app_session ? 'Review the email, then choose Approve or Reject.' : 'Use the dashboard approval link.';
+  }
+  window.addEventListener('message', async event => {
+    // Email frames are untrusted: even synthetic JSON-RPC from a child is ignored.
+    if (event.source !== parent || !event.data || event.data.jsonrpc !== '2.0') return;
+    const message = event.data, entry = pending.get(message.id);
+    if (entry) {
+      clearTimeout(entry.timeout); pending.delete(message.id);
+      if (message.error) entry.reject(new Error('Host refused the request.')); else entry.resolve(message.result);
+    } else if (message.method === 'ui/notifications/tool-result' && !data.preview) {
+      const uri = message.params?._meta?.ui?.resourceUri;
+      if (typeof uri !== 'string' || !/^ui:\/\/sendinel\/approval\/[a-zA-Z0-9-]+$/.test(uri)) return;
+      try {
+        await loadApproval(uri);
+      } catch (error) { status.textContent = error.message; }
+    }
+  });
+  buttons.forEach(button => button.addEventListener('click', async event => {
+    if (!event.isTrusted || !ready || !data.app_session || started) return;
+    started = true; buttons.forEach(b => b.disabled = true); status.textContent = 'Recording decision…';
+    try {
+      const result = await request('tools/call',{name:data.tool,arguments:{approval_id:data.approval_id,decision:button.id === 'approve' ? 'approve':'reject',app_session:data.app_session}});
+      data.app_session = undefined;
+      status.textContent = result.isError ? 'Decision refused. Open the dashboard approval link.' : 'Decision recorded. The next action call with approval_id can apply an approved payload.';
+    } catch (error) { data.app_session = undefined; status.textContent = error.message; }
+  }));
+  render();
+  request('ui/initialize',{appInfo:{name:'Sendinel approval',version:'1.0.0'},appCapabilities:{},protocolVersion:data.protocolVersion})
+    .then(async result => {
+      if (result.protocolVersion !== data.protocolVersion) throw new Error('Unsupported Apps protocol; open the dashboard approval link.');
+      ready = true; notify('ui/notifications/initialized',{}); render();
+      if (data.approval_id && !data.app_session) await loadApproval('ui://sendinel/approval/' + encodeURIComponent(data.approval_id));
+      status.textContent = data.preview ? (data.app_session ? 'Review the email, then choose Approve or Reject.' : 'Use the dashboard approval link.') : 'Waiting for approval preview…';
+    }).catch(error => { status.textContent = error.message; });
+})();
+</script></body></html>`;

package/build/auth.js CHANGED Viewed

@@ -75,6 +75,7 @@ export async function validateKey(key) {
         scopes: row.scopes,
         toolGroups: resolveToolGroupsForPlan(plan, row.tool_groups),
         approvalMode: row.approval_mode ?? 'standard',
+        actsAsUserId: row.acts_as_user_id ?? null,
     };
 }
 export async function authenticateBearer(token, overrideProjectId) {

package/build/index.js CHANGED Viewed

@@ -7,7 +7,9 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { registerAllTools, SENDINEL_SERVER_INSTRUCTIONS } from './server.js';
+import { registerAllTools, SENDINEL_SERVER_INSTRUCTIONS, isAgentConnection, isTesterConnection } from './server.js';
+import { installApprovalElicitation } from './lib/approval-elicitation.js';
+import { createHumanApprovalCallback } from './lib/approval-human-callback.js';
 import { registerAllPrompts } from './prompts.js';
 import { runWithClient } from './db.js';
 import { initProjectClient, resolveProjectClientStrict, TenantResolutionError } from './byod-client.js';
@@ -38,6 +40,10 @@ async function runStdio() {
     }
     registerAllTools(server, { toolGroups, scopes });
     registerAllPrompts(server, { toolGroups, scopes });
+    if (!isAgentConnection(info.scopes) && !isTesterConnection(info.scopes)) {
+        installApprovalElicitation(server, { projectId: info.projectId, userId: info.actsAsUserId,
+            createHumanDecision: createHumanApprovalCallback });
+    }
     const t = new StdioServerTransport();
     await server.connect(t);
     process.stderr.write('Sendinel MCP server running (stdio)\n');

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

@@ -47,6 +47,7 @@ export interface ApprovalResult {
     /** One-tap approval page; works on a phone and needs no project switching (#3661). */
     approve_url: string;
     preview_text: string;
+    decision_status: 'decision_pending' | 'approved' | 'rejected';
     message: string;
 }
 export declare function approvalPageUrl(approvalId: string): string;

package/build/lib/action-approvals.js CHANGED Viewed

@@ -4,6 +4,8 @@ import { db, requestContext } from '../db.js';
 import { getProjectId } from '../project.js';
 import { captureApprovalSnapshot, withoutApprovalSnapshot } from './approval-snapshot.js';
 import { fireWebhookEvent } from './webhook-events.js';
+import { offerApprovalApp } from './approval-app.js';
+import { elicitApproval } from './approval-elicitation.js';
 /**
  * Action approval tiers:
  *
@@ -362,8 +364,10 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         resource_id: params.resource_id ?? params.campaign_id ?? params.contact_id ?? null,
         requested_by: apiKeyId ?? null,
     }, getProjectId()).catch(() => { });
-    return {
+    return elicitApproval({
         requires_approval: true,
+        ...offerApprovalApp({ id: data.id, action, params: frozenParams, summary, tier, expires_at: expiresAt,
+            payload_hash: approvalPayloadHash(action, frozenParams) }),
         approval_id: data.id,
         tier,
         action,
@@ -373,7 +377,7 @@ export async function requestApproval(action, params, apiKeyId, channelContext,
         approve_url: approvalPageUrl(data.id),
         preview_text: buildApprovalPreview({ action, params: frozenParams, summary }).plain_summary,
         message: `This action requires human approval. A notification has been sent to your dashboard. Approval ID: ${data.id}. Check status with: poll this approval_id, or wait for the webhook callback (event: approval.decided). Token expires in 24 hours.`,
-    };
+    }, { action, params: frozenParams, summary }, getProjectId());
 }
 /**
  * Check if an approval token has been approved.

package/build/lib/approval-app-conventions.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+export declare const APPROVAL_APP: {
+    readonly mimeType: "text/html;profile=mcp-app";
+    readonly uri: 'ui://sendinel/approval';
+    readonly template: 'ui://sendinel/approval/{approval_id}';
+    readonly protocolVersion: '2026-01-26';
+    readonly tool: 'approval_app_decide';
+    readonly resultUriKey: 'resourceUri';
+    readonly csp: {
+        readonly connectDomains: readonly [];
+        readonly resourceDomains: readonly ['https:'];
+        readonly frameDomains: readonly ["'self'"];
+    };
+};
+export declare const approvalAppResourceMeta: {
+    ui: {
+        csp: {
+            readonly connectDomains: readonly [];
+            readonly resourceDomains: readonly ['https:'];
+            readonly frameDomains: readonly ["'self'"];
+        };
+        permissions: {};
+        prefersBorder: boolean;
+    };
+};
+export declare const APPROVAL_APP_SESSION_META = "sendinel/app_session";

package/build/lib/approval-app-conventions.js ADDED Viewed

@@ -0,0 +1,24 @@
+import { MCP_APP_MIME_TYPE } from './approval-capabilities.js';
+// Confirmed against ext-apps specification/2026-01-26/apps.mdx and src/spec.types.ts.
+// SDK 1.32 carries _meta through, but visibility filtering is the Apps HOST's duty.
+export const APPROVAL_APP = {
+    mimeType: MCP_APP_MIME_TYPE,
+    uri: 'ui://sendinel/approval',
+    template: 'ui://sendinel/approval/{approval_id}',
+    protocolVersion: '2026-01-26',
+    tool: 'approval_app_decide',
+    // UNCONFIRMED: dynamic resourceUri in a TOOL RESULT is requested by #4280;
+    // the stable spec defines it on tool definitions. The static definition URI
+    // also works: its app reads the dynamic resource using the tool-result metadata.
+    resultUriKey: 'resourceUri',
+    // UNCONFIRMED: host acceptance of scheme sources / srcdoc in these domain lists.
+    // Needed for real-email HTTPS images in nested srcdoc, without external scripts,
+    // CSS or outer-app fetch. Hosts may further restrict; live runbook must check.
+    csp: { connectDomains: [], resourceDomains: ['https:'], frameDomains: ["'self'"] },
+};
+export const approvalAppResourceMeta = { ui: { csp: APPROVAL_APP.csp, permissions: {}, prefersBorder: true } };
+// Custom, host/app-only metadata. Hosts must keep this OUT of model context,
+// including when the model reads a resource. UNCONFIRMED per client until live
+// runbook verifies resource metadata isolation (tool metadata isolation alone
+// is insufficient). Never embed this value in resource text.
+export const APPROVAL_APP_SESSION_META = 'sendinel/app_session';

package/build/lib/approval-app.d.ts ADDED Viewed

@@ -0,0 +1,43 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type AppApproval = {
+    id: string;
+    action: string;
+    params: Record<string, any>;
+    summary?: string;
+    tier: string;
+    expires_at: string;
+    payload_hash: string;
+};
+/** Only frozen facts enter this view. No live reads or model-supplied display overrides. */
+export declare function approvalAppView(approval: AppApproval): {
+    approval_id: string;
+    preview: import("@sendinel/domain").ApprovalPreviewModel;
+    diff: {
+        field: string;
+        before: string;
+        after: string;
+    }[];
+    payload_hash: string;
+    expires_at: string;
+};
+/** A TypeScript string bundles the single HTML file into build/ without a copy step. */
+export declare function renderApprovalApp(approval?: AppApproval): string;
+export declare function registerApprovalAppResources(server: McpServer, read: (id: string) => Promise<{
+    html: string;
+    appSession: string;
+}>): void;
+/** Called only after the core has persisted its frozen payload. Tokens never enter tool results. */
+export declare function offerApprovalApp(approval: AppApproval): {
+    _meta?: {
+        ui: {
+            resourceUri: string;
+        };
+    };
+};
+/** Transport boundary, outside the model catalog and gateway catalog. Apps hosts MUST
+ * honor visibility. Even a raw model tools/call cannot decide without the resource-only token.
+ * The SDK Server instance is the connection boundary; no cross-request/global token cache.
+ */
+export declare function installApprovalApp(server: McpServer, options?: {
+    scopes?: string[];
+}, approvalTool?: (name: string) => boolean): McpServer;

package/build/lib/approval-app.js ADDED Viewed

@@ -0,0 +1,161 @@
+import { randomBytes } from 'node:crypto';
+import { buildApprovalPreview } from '@sendinel/domain';
+import { APPROVAL_APP, APPROVAL_APP_SESSION_META } from './approval-app-conventions.js';
+import { APPROVAL_APP_HTML } from '../approval-app-html.js';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { approvalAppResourceMeta } from './approval-app-conventions.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { z } from 'zod';
+import { requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { approval_channel_available } from './approval-capabilities.js';
+import { createHumanApprovalCallback } from './approval-human-callback.js';
+/** Only frozen facts enter this view. No live reads or model-supplied display overrides. */
+export function approvalAppView(approval) {
+    const preview = buildApprovalPreview(approval);
+    const p = approval.params;
+    const snapshot = p.__approval_snapshot ?? {};
+    const before = p.previous_campaign ?? p.previous_site ?? snapshot.campaigns?.[0] ?? snapshot.sites?.[0] ?? {};
+    const after = p.updates ?? p.payload ?? p;
+    const fields = ['trigger_event_name', 'trigger_tag', 'trigger_type', 'trigger_config', 'send_class',
+        'physical_address', 'unsub_link_enabled', 'unsub_footer_template'];
+    const diff = fields.filter(key => Object.hasOwn(after, key) && JSON.stringify(before[key]) !== JSON.stringify(after[key]))
+        .map(key => ({ field: key, before: before[key] === undefined ? 'unknown' : JSON.stringify(before[key]),
+        after: JSON.stringify(after[key]) }));
+    return { approval_id: approval.id, preview, diff, payload_hash: approval.payload_hash, expires_at: approval.expires_at };
+}
+/** A TypeScript string bundles the single HTML file into build/ without a copy step. */
+export function renderApprovalApp(approval) {
+    const nonce = randomBytes(24).toString('base64');
+    const data = { ...(approval ? approvalAppView(approval) : {}), sessionMetaKey: APPROVAL_APP_SESSION_META,
+        tool: APPROVAL_APP.tool, protocolVersion: APPROVAL_APP.protocolVersion };
+    // Never interpolate untrusted text as markup, even into an application/json script.
+    const json = JSON.stringify(data).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
+    return APPROVAL_APP_HTML.replaceAll('__NONCE__', nonce).replace('__APP_DATA__', () => json);
+}
+export function registerApprovalAppResources(server, read) {
+    const config = { mimeType: APPROVAL_APP.mimeType, _meta: approvalAppResourceMeta };
+    const result = (uri, text, appSession) => ({ contents: [{ uri: uri.href,
+                mimeType: APPROVAL_APP.mimeType, text, _meta: { ...approvalAppResourceMeta,
+                    ...(appSession ? { [APPROVAL_APP_SESSION_META]: appSession } : {}) } }] });
+    server.registerResource('approval-app', APPROVAL_APP.uri, config, async (uri) => result(uri, renderApprovalApp()));
+    server.registerResource('approval-preview', new ResourceTemplate(APPROVAL_APP.template, { list: undefined }), config, async (uri, variables) => { const view = await read(String(variables.approval_id)); return result(uri, view.html, view.appSession); });
+}
+const runtimes = new WeakMap();
+const calls = new AsyncLocalStorage();
+const resourceUri = (id) => `${APPROVAL_APP.uri}/${encodeURIComponent(id)}`;
+function identity() {
+    const context = requestContext();
+    // Do not attribute an API key owner, agent or tester's click to a human.
+    return context?.channelVerified === true && context.actorId && context.authKind !== 'scoped_jwt'
+        ? { userId: context.actorId, projectId: getProjectId() } : null;
+}
+function matches(offer) {
+    const actor = identity();
+    return !!actor && actor.projectId === offer.projectId && actor.userId === offer.userId;
+}
+function live(approval) {
+    return Number.isFinite(Date.parse(approval.expires_at)) && Date.parse(approval.expires_at) > Date.now();
+}
+function prune(runtime) {
+    for (const [id, offer] of runtime.offers)
+        if (!live(offer.approval))
+            runtime.offers.delete(id);
+    for (const [token, session] of runtime.sessions)
+        if (!live(session.offer.approval))
+            runtime.sessions.delete(token);
+}
+/** Called only after the core has persisted its frozen payload. Tokens never enter tool results. */
+export function offerApprovalApp(approval) {
+    const runtime = calls.getStore(), actor = identity();
+    if (!runtime || !runtime.canDecide || !actor || approval.tier === 'protected' ||
+        approval_channel_available(runtime.server.server) !== 'mcp_app')
+        return {};
+    prune(runtime);
+    if (runtime.offers.size >= 128 || !live(approval))
+        return {};
+    runtime.offers.set(approval.id, { approval: structuredClone(approval), ...actor });
+    return { _meta: { ui: { [APPROVAL_APP.resultUriKey]: resourceUri(approval.id) } } };
+}
+/** Transport boundary, outside the model catalog and gateway catalog. Apps hosts MUST
+ * honor visibility. Even a raw model tools/call cannot decide without the resource-only token.
+ * The SDK Server instance is the connection boundary; no cross-request/global token cache.
+ */
+export function installApprovalApp(server, options = {}, approvalTool = () => false) {
+    // Catalog collectors have no transport/resource API; never expose this tool through them.
+    if (!server.server || typeof server.registerResource !== 'function')
+        return server;
+    let runtime = runtimes.get(server.server);
+    if (!runtime) {
+        runtime = { server, connectionId: randomBytes(32).toString('hex'), offers: new Map(), sessions: new Map(),
+            canDecide: !options.scopes?.some(scope => scope === 'tester' || scope === 'agent') };
+        runtimes.set(server.server, runtime);
+        const bound = runtime;
+        registerApprovalAppResources(server, async (id) => {
+            prune(bound);
+            const offer = bound.offers.get(id);
+            if (!offer || !matches(offer) || approval_channel_available(server.server) !== 'mcp_app')
+                throw new Error('Approval app unavailable on this connection; use approve_url.');
+            // One outstanding render session per approval. Re-render invalidates the old view.
+            for (const [token, session] of bound.sessions)
+                if (session.offer === offer)
+                    bound.sessions.delete(token);
+            const callback = createHumanApprovalCallback({ approvalId: id, projectId: offer.projectId,
+                userId: offer.userId, connectionId: bound.connectionId, channel: 'mcp_app' });
+            const token = randomBytes(32).toString('base64url');
+            bound.sessions.set(token, { offer, callback });
+            // Resource text can be shown to the model; the bearer belongs exclusively
+            // in host/app metadata, never HTML, a tool result, a URL or an audit entry.
+            return { html: renderApprovalApp(offer.approval), appSession: token };
+        });
+        const registerDecide = () => server.registerTool(APPROVAL_APP.tool, {
+            description: 'Record the human decision from this connection’s rendered approval app.',
+            _meta: { ui: { visibility: ['app'] } },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            inputSchema: z.object({ approval_id: z.string(), decision: z.enum(['approve', 'reject']), app_session: z.string().min(1) }).strict(),
+        }, async ({ approval_id, decision, app_session }) => {
+            prune(bound);
+            const session = bound.sessions.get(app_session);
+            const refused = () => ({ isError: true, content: [{ type: 'text', text: 'Decision refused; use the dashboard approval link.' }] });
+            if (!bound.canDecide || !session || session.offer.approval.id !== approval_id || !matches(session.offer) ||
+                !live(session.offer.approval) || approval_channel_available(server.server) !== 'mcp_app')
+                return refused();
+            // Claim before awaiting the callback, so concurrent clicks cannot reuse a session.
+            bound.sessions.delete(app_session);
+            bound.offers.delete(approval_id);
+            const accepted = await session.callback.complete({ interactionId: session.callback.interactionId,
+                connectionId: bound.connectionId, decision });
+            return accepted ? { content: [{ type: 'text', text: 'Decision recorded.' }] } : refused();
+        });
+        const previousInitialized = server.server.oninitialized;
+        server.server.oninitialized = () => {
+            previousInitialized?.();
+            if (bound.canDecide && approval_channel_available(server.server) === 'mcp_app')
+                registerDecide();
+        };
+        const previousClose = server.server.onclose;
+        server.server.onclose = () => { bound.offers.clear(); bound.sessions.clear(); previousClose?.(); };
+    }
+    const bound = runtime;
+    return new Proxy(server, { get(target, prop, receiver) {
+            if (prop !== 'registerTool')
+                return Reflect.get(target, prop, receiver);
+            return (name, config, handler) => target.registerTool(name, approvalTool(name) || name === 'invoke_tool' ? { ...config, _meta: { ...config._meta, ui: { resourceUri: APPROVAL_APP.uri } } } : config, async (...args) => calls.run(calls.getStore() ?? bound, async () => {
+                const result = await handler(...args);
+                // Existing tools serialize ApprovalResult into content; promote ONLY its UI
+                // reference to MCP result metadata. The resource token is never in that object.
+                for (const content of result?.content ?? []) {
+                    if (content.type !== 'text')
+                        continue;
+                    try {
+                        const value = JSON.parse(content.text);
+                        if (value.requires_approval === true && value._meta?.ui?.resourceUri) {
+                            return { ...result, _meta: { ...result._meta, ui: value._meta.ui } };
+                        }
+                    }
+                    catch { /* Non-JSON text fallback. */ }
+                }
+                return result;
+            }));
+        } });
+}

package/build/lib/approval-elicitation.d.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RequestId } from '@modelcontextprotocol/sdk/types.js';
+type Decision = 'approve' | 'reject';
+type HumanCallback = {
+    interactionId: string;
+    complete(response: {
+        interactionId: string;
+        connectionId: string;
+        decision: Decision;
+    }): Promise<boolean>;
+};
+/** Injected at authenticated transport startup, never taken from tool arguments. */
+type TransportBinding = {
+    projectId: string;
+    userId?: string | null;
+    createHumanDecision(binding: {
+        approvalId: string;
+        projectId: string;
+        connectionId: string;
+        userId: string;
+        channel: 'mcp_elicitation';
+    }): HumanCallback;
+};
+type RequestExtra = {
+    requestId?: RequestId;
+    signal?: AbortSignal;
+};
+export declare function installApprovalElicitation(server: McpServer, binding: TransportBinding): void;
+/** Called by the registry wrapper with SDK-owned extra, outside parsed model arguments. */
+export declare function runWithApprovalElicitation<T>(server: McpServer, extra: RequestExtra | undefined, run: () => T): T;
+type ApprovalFallback = {
+    approval_id: string;
+    approve_url: string;
+    preview_text: string;
+    tier: string;
+};
+export type ElicitationDecision = 'decision_pending' | 'approved' | 'rejected';
+/** All outcomes retain the ordinary approval link/text. Approval never applies the action. */
+export declare function elicitApproval<T extends ApprovalFallback>(result: T, frozen: {
+    action: string;
+    params: unknown;
+    summary: string;
+}, projectId: string): Promise<T & {
+    decision_status: ElicitationDecision;
+}>;
+export {};

package/build/lib/approval-elicitation.js ADDED Viewed

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { buildApprovalPreview, isHumanApprovalChannel } from '@sendinel/domain';
+import { db } from '../db.js';
+import { approval_channel_available, probeApprovalCapabilities } from './approval-capabilities.js';
+// Keyed by the SDK Server, not the McpServer wrapper: other installers (the Apps tier) wrap
+// McpServer in a Proxy, which changes the wrapper's identity but never the connection's Server.
+const sessions = new WeakMap();
+const requests = new AsyncLocalStorage();
+const TIMEOUT_MS = 60_000;
+export function installApprovalElicitation(server, binding) {
+    sessions.set(server.server, { ...binding, connectionId: randomUUID() });
+}
+/** Called by the registry wrapper with SDK-owned extra, outside parsed model arguments. */
+export function runWithApprovalElicitation(server, extra, run) {
+    const binding = sessions.get(server.server);
+    // Nested gateway dispatch retains the originating connection/request. The hosted bridge
+    // has no binding and cannot impersonate its outer HTTP client's capabilities.
+    if (!binding || requests.getStore())
+        return run();
+    return requests.run({ ...binding, ...extra, server }, run);
+}
+/** All outcomes retain the ordinary approval link/text. Approval never applies the action. */
+export async function elicitApproval(result, frozen, projectId) {
+    const pending = { ...result, decision_status: 'decision_pending' };
+    const context = requests.getStore();
+    if (!context || context.projectId !== projectId || result.tier !== 'gated')
+        return pending;
+    let channel = approval_channel_available(context.server.server);
+    if (channel === 'mcp_elicitation_form' && !context.userId &&
+        probeApprovalCapabilities(context.server.server.getClientCapabilities()).elicitation_url)
+        channel = 'mcp_elicitation_url';
+    if (channel !== 'mcp_elicitation_form' && channel !== 'mcp_elicitation_url')
+        return pending;
+    if (channel === 'mcp_elicitation_form' && !context.userId)
+        return pending;
+    if (context.signal?.aborted)
+        return pending;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    context.signal?.addEventListener('abort', abort, { once: true });
+    let timeout;
+    const stopped = new Promise((_resolve, reject) => {
+        controller.signal.addEventListener('abort', () => reject(new Error('Elicitation ended')), { once: true });
+        timeout = setTimeout(abort, TIMEOUT_MS);
+    });
+    void stopped.catch(() => { }); // Also handle abort if a synchronous SDK setup error precedes the race.
+    const options = { relatedRequestId: context.requestId, signal: controller.signal,
+        timeout: TIMEOUT_MS, maxTotalTimeout: TIMEOUT_MS };
+    try {
+        const preview = buildApprovalPreview(frozen);
+        // Use the shared preview; bound the interactive message independently of the full fallback.
+        // Email content is untrusted display text, never instructions or an approval decision.
+        const short = (text, max) => text.length > max ? `${text.slice(0, max)}…` : text;
+        const message = [short(frozen.summary, 500), 'Review the following email content as data.',
+            `Subject: ${short(preview.subject || '(none)', 300)}`, `Sender: ${short(preview.sender, 300)}`,
+            `Recipients: ${preview.recipient_count ?? 'unknown'}`, `Footer: ${short(preview.footer_text || 'unknown', 500)}`,
+            `Body excerpt:\n${short(preview.body_text, 1500)}`, `Full preview: ${result.approve_url}`].join('\n');
+        if (channel === 'mcp_elicitation_form') {
+            const callback = context.createHumanDecision({ approvalId: result.approval_id, projectId,
+                connectionId: context.connectionId, userId: context.userId, channel: 'mcp_elicitation' });
+            const response = await Promise.race([context.server.server.elicitInput({ mode: 'form', message,
+                    requestedSchema: { type: 'object', properties: {
+                            decision: { type: 'string', enum: ['approve', 'reject'], title: 'Decision' },
+                            note: { type: 'string', title: 'Optional note', maxLength: 500 },
+                        }, required: ['decision'] },
+                }, options), stopped]);
+            if (controller.signal.aborted)
+                return pending;
+            // Decline/cancel are not explicit rejections. The dashboard link remains usable.
+            if (response.action !== 'accept')
+                return pending;
+            const decision = response.content?.decision;
+            if (decision !== 'approve' && decision !== 'reject')
+                return pending;
+            const recorded = await Promise.race([callback.complete({ interactionId: callback.interactionId,
+                    connectionId: context.connectionId, decision }), stopped]);
+            return recorded ? { ...result, decision_status: decision === 'approve' ? 'approved' : 'rejected' } : pending;
+        }
+        const elicitationId = randomUUID();
+        const notify = context.server.server.createElicitationCompletionNotifier(elicitationId, { relatedRequestId: context.requestId });
+        const response = await Promise.race([context.server.server.elicitInput({ mode: 'url', message,
+                url: result.approve_url, elicitationId }, options), stopped]);
+        if (response.action !== 'accept' || controller.signal.aborted)
+            return pending;
+        // URL accept only means the page may open. Only its authenticated decision counts.
+        // Observe while this request is alive; do not retain a background poller after timeout.
+        while (!controller.signal.aborted) {
+            const source = db();
+            const client = typeof source.schema === 'function' ? source.schema('email') : source;
+            const { data, error } = await Promise.race([client.from('action_approvals')
+                    .select('status, decided_via').eq('id', result.approval_id).eq('project_id', projectId).maybeSingle(), stopped]);
+            if (error || !data)
+                return pending;
+            if ((data.status === 'approved' || data.status === 'rejected') && isHumanApprovalChannel(data.decided_via)) {
+                await Promise.race([notify(), stopped]);
+                return { ...result, decision_status: data.status };
+            }
+            await Promise.race([new Promise(resolve => {
+                    const timer = setTimeout(done, 1000);
+                    function done() { clearTimeout(timer); controller.signal.removeEventListener('abort', done); resolve(); }
+                    controller.signal.addEventListener('abort', done, { once: true });
+                }), stopped]);
+        }
+    }
+    catch {
+        // Unsupported SDK modes, disconnections, timeouts and refused DB writes fail to the link.
+        // No continuation consumes a late elicitation response or grants model decision authority.
+    }
+    finally {
+        clearTimeout(timeout);
+        context.signal?.removeEventListener('abort', abort);
+        controller.abort();
+    }
+    return pending;
+}

package/build/server.js CHANGED Viewed

@@ -1,4 +1,6 @@
 import { installApprovalCapabilityProbe } from './lib/approval-capabilities.js';
+import { installApprovalApp } from './lib/approval-app.js';
+import { runWithApprovalElicitation } from './lib/approval-elicitation.js';
 import { runWithToolContext } from './db.js';
 import { isApprovalGatedAction } from './lib/action-approvals.js';
 import { registerAgentMailboxTools } from './tools/agent-mailboxes.js';
@@ -354,11 +356,11 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                                 const text = agent ? agentConnectionRefusal(name) : tester ? testerConnectionRefusal(name) : `Forbidden: this action requires "${required}" scope.`;
                                 return { content: [{ type: 'text', text }] };
                             }
-                            return runWithToolContext(toolGroup, name, () => handler(...args));
+                            return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)));
                         };
                         return target.registerTool(name, config, guardedHandler);
                     }
-                    return target.registerTool(name, config, (...args) => runWithToolContext(toolGroup, name, () => handler(...args)));
+                    return target.registerTool(name, config, (...args) => runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args))));
                 };
             }
             return Reflect.get(target, prop, receiver);
@@ -380,6 +382,7 @@ export const SENDINEL_SERVER_INSTRUCTIONS = [
 export function registerAllTools(server, options) {
     if (server.server)
         installApprovalCapabilityProbe(server.server);
+    server = installApprovalApp(server, options, isApprovalGatedAction);
     const rawScopes = options?.scopes ?? [];
     if (rawScopes.includes('gateway')) {
         const permissionScopes = rawScopes.filter((scope) => scope !== 'gateway');

package/package.json CHANGED Viewed

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