@sendinel/mcp-server 1.0.146 → 1.0.147

package/build/lib/action-approvals.js

@@ -380,7 +380,9 @@ export async function checkApproval(approvalId, options = {}) {
         .eq('id', approvalId)
         .eq('project_id', getProjectId())
         .maybeSingle();
-    if (error || !data)
+    if (error)
+        throw error;
+    if (!data)
         return { approved: false, status: 'not_found' };
     if (options.action && data.action !== options.action) {
         return { approved: false, status: 'action_mismatch' };

package/build/lib/db-error.d.ts

@@ -1,10 +1,23 @@
-/** Public tool errors must not expose SQL, constraint names or database internals. */
-export declare function dbToolError(error: {
-    code?: string;
-    message?: string;
-}, message?: string): {
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Stable, caller-safe codes shared by MCP tools and hosted usage tracking. */
+export declare const TOOL_ERROR_CODES: readonly ['conflict', 'not_found', 'validation_failed', 'forbidden', 'plan_limit', 'internal_error'];
+export type ToolErrorCode = typeof TOOL_ERROR_CODES[number];
+/** Preserve the original compact helper's public wording and serialization. */
+export declare function mapDbError(error: unknown): {
     error: string;
-    code: string;
+    code: ToolErrorCode;
+};
+export declare function dbErrorResult(error: unknown): {
+    isError: boolean;
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};
+/** Preserve the original pretty-printed helper's public wording. Never copy diagnostics. */
+export declare function dbToolError(error: unknown, message?: string): {
+    error: string;
+    code: "conflict" | "forbidden" | "internal_error" | "not_found" | "plan_limit" | "validation_failed";
 };
 /** Mark coded failures as MCP errors so the hosted api_usage classifier sees them. */
 export declare function toolError(body: unknown): {
@@ -14,3 +27,23 @@ export declare function toolError(body: unknown): {
         text: string;
     }[];
 };
+/** Machine-code classification for api_usage only. Never rewrite response codes.
+ * Keys are case-insensitive; every supported legacy spelling is listed explicitly.
+ * Existing usage-only policy classes remain supported alongside the six tool classes. */
+export declare const API_USAGE_ERROR_CODE_MAP: Readonly<Record<string, string>>;
+type ToolResult = {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+};
+/** Add a stable class to refusals without dropping existing fields or success data. */
+export declare function codedToolResult<T extends ToolResult>(result: T): T;
+/** SDK, HTTP and gateway registration share the same exception/refusal boundary. */
+export declare function withToolErrors(handler: (...args: any[]) => any): (...args: any[]) => Promise<any>;
+/** Include SDK validation, which runs before registered tool handlers. */
+export declare function installToolErrorBoundary(server: McpServer): void;
+export {};

package/build/lib/db-error.js

@@ -1,17 +1,227 @@
-/** Public tool errors must not expose SQL, constraint names or database internals. */
+import { CallToolRequestSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+/** Stable, caller-safe codes shared by MCP tools and hosted usage tracking. */
+export const TOOL_ERROR_CODES = ['conflict', 'not_found', 'validation_failed', 'forbidden', 'plan_limit', 'internal_error'];
+function databaseCode(error) {
+    const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+    if (code === '23505')
+        return 'conflict';
+    if (code === '23503' || code === 'PGRST116')
+        return 'not_found';
+    if (code === '42501')
+        return 'forbidden';
+    if (code.startsWith('23') || code.startsWith('22'))
+        return 'validation_failed';
+    return 'internal_error';
+}
+/** Preserve the original compact helper's public wording and serialization. */
+export function mapDbError(error) {
+    const code = databaseCode(error);
+    const messages = {
+        conflict: 'A record with these values already exists.',
+        not_found: 'The requested or referenced record was not found.',
+        validation_failed: 'The supplied values are not valid. Check the input and try again.',
+        forbidden: 'Operation forbidden.',
+        plan_limit: 'Plan limit reached.',
+        internal_error: 'The operation could not be completed. Please try again later.',
+    };
+    return { error: messages[code], code };
+}
+export function dbErrorResult(error) {
+    console.warn('[mcp] Database operation failed:', error);
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(mapDbError(error)) }] };
+}
+/** Preserve the original pretty-printed helper's public wording. Never copy diagnostics. */
 export function dbToolError(error, message = 'Unable to complete database operation') {
-    if (error.code === '23505')
-        return { error: 'A record with these values already exists', code: 'conflict' };
-    if (error.code === '23503')
-        return { error: 'Referenced record not found', code: 'not_found' };
-    if (error.code === '42501')
-        return { error: 'Operation forbidden', code: 'forbidden' };
-    if (error.code?.startsWith('22') || error.code === '23514' || error.code === '23502') {
-        return { error: 'Invalid record values', code: 'validation_failed' };
-    }
-    return { error: message, code: 'internal_error' };
+    const code = databaseCode(error);
+    const messages = {
+        conflict: 'A record with these values already exists',
+        not_found: 'Referenced record not found',
+        forbidden: 'Operation forbidden',
+        validation_failed: 'Invalid record values',
+        plan_limit: 'Plan limit reached',
+        internal_error: message,
+    };
+    return { error: messages[code], code };
 }
 /** Mark coded failures as MCP errors so the hosted api_usage classifier sees them. */
 export function toolError(body) {
     return { isError: true, content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
 }
+/** Machine-code classification for api_usage only. Never rewrite response codes.
+ * Keys are case-insensitive; every supported legacy spelling is listed explicitly.
+ * Existing usage-only policy classes remain supported alongside the six tool classes. */
+export const API_USAGE_ERROR_CODE_MAP = {
+    'approval_call_takes_only_approval_id': 'validation_failed',
+    'audience_not_understood': 'validation_failed',
+    'audience_required': 'validation_failed',
+    'bad_id': 'validation_failed',
+    'bad_id_format': 'validation_failed',
+    'bad_request': 'validation_failed',
+    'campaigns_required': 'validation_failed',
+    'content_required': 'validation_failed',
+    'empty_audience': 'validation_failed',
+    'empty_body': 'validation_failed',
+    'empty_cohort': 'validation_failed',
+    'empty_segment': 'validation_failed',
+    'invalid_campaign_type': 'validation_failed',
+    'invalid_condition_value': 'validation_failed',
+    'invalid_date': 'validation_failed',
+    'invalid_field': 'validation_failed',
+    'invalid_id': 'validation_failed',
+    'invalid_input': 'validation_failed',
+    'invalid_json': 'validation_failed',
+    'invalid_param': 'validation_failed',
+    'invalid_project': 'validation_failed',
+    'invalid_recipient': 'validation_failed',
+    'invalid_segment_rules': 'validation_failed',
+    'invalid_send_at': 'validation_failed',
+    'invalid_set': 'validation_failed',
+    'invalid_slug': 'validation_failed',
+    'invalid_status': 'validation_failed',
+    'invalid_target': 'validation_failed',
+    'invalid_url': 'validation_failed',
+    'missing_field': 'validation_failed',
+    'no_body': 'validation_failed',
+    'no_emails': 'validation_failed',
+    'not_activatable': 'validation_failed',
+    'not_imported': 'validation_failed',
+    'site_mismatch': 'validation_failed',
+    'step_wait_not_set': 'validation_failed',
+    'subject_required': 'validation_failed',
+    'switch_not_supported': 'validation_failed',
+    'unprocessable_entity': 'validation_failed',
+    'validation': 'validation_failed',
+    'validation_failed': 'validation_failed',
+    '23505': 'conflict',
+    'conflict': 'conflict',
+    'content_changed_since_approval': 'conflict',
+    'duplicate': 'conflict',
+    'duplicate_email': 'conflict',
+    'duplicate_name': 'conflict',
+    'proposal_conflict': 'conflict',
+    'site_changed_or_not_found': 'conflict',
+    'slug_unavailable': 'conflict',
+    '23503': 'not_found',
+    'campaign_not_found': 'not_found',
+    'list_not_found': 'not_found',
+    'not_found': 'not_found',
+    'segment_not_found': 'not_found',
+    'site_not_found': 'not_found',
+    'approval_forbidden': 'forbidden',
+    'chat_confirm_not_enabled': 'forbidden',
+    'forbidden': 'forbidden',
+    'implicit_access': 'forbidden',
+    'insufficient_scope': 'forbidden',
+    'last_owner': 'forbidden',
+    'no_api_key': 'forbidden',
+    'no_connection': 'forbidden',
+    'no_org': 'forbidden',
+    'no_synchronex_bundle': 'forbidden',
+    'org_mismatch': 'forbidden',
+    'project_access_denied': 'forbidden',
+    'project_scope_mismatch': 'forbidden',
+    'unauthorized': 'forbidden',
+    'agent_mailbox_limit_reached': 'plan_limit',
+    'ai_draft_limit_reached': 'plan_limit',
+    'contact_limit_reached': 'plan_limit',
+    'limit_reached': 'plan_limit',
+    'plan_limit': 'plan_limit',
+    'plan_required': 'plan_limit',
+    'quota_exceeded': 'plan_limit',
+    'activation_failed': 'internal_error',
+    'ai_not_configured': 'internal_error',
+    'ai_unavailable': 'internal_error',
+    'approval_lookup_failed': 'internal_error',
+    'audience_lookup_failed': 'internal_error',
+    'campaign_create_failed': 'internal_error',
+    'campaign_lookup_failed': 'internal_error',
+    'campaign_visibility_query_failed': 'internal_error',
+    'conversion_not_ready': 'internal_error',
+    'draft_failed': 'internal_error',
+    'enrollment_failed': 'internal_error',
+    'event_intake_failed': 'internal_error',
+    'generation_failed': 'internal_error',
+    'image_generation_failed': 'internal_error',
+    'internal_error': 'internal_error',
+    'internal_server_error': 'internal_error',
+    'one_send_lookup_failed': 'internal_error',
+    'segment_lookup_failed': 'internal_error',
+    'set_lookup_failed': 'internal_error',
+    'site_lookup_failed': 'internal_error',
+    'step_create_failed': 'internal_error',
+    'step_lookup_failed': 'internal_error',
+    'survey_link_not_ready': 'internal_error',
+    'sandbox_blocked': 'sandbox_blocked',
+    'send_allowlist_refused': 'send_allowlist_refused',
+    'rate_limited': 'rate_limited',
+};
+/** Add a stable class to refusals without dropping existing fields or success data. */
+export function codedToolResult(result) {
+    let failed = result.isError === true;
+    const content = result.content.map(block => {
+        if (block.type !== 'text' || typeof block.text !== 'string')
+            return block;
+        let body;
+        let textCode;
+        try {
+            body = JSON.parse(block.text);
+        }
+        catch {
+            // Legacy textual refusal paths. Ordinary text successes remain byte-for-byte.
+            if (!failed && !/^(?:Error:|Forbidden:|Permission denied:|Unknown skill:|Provide |Nothing to update|No fields to update|(?:Contact|Project|Source) (?:or.* )?not found)/i.test(block.text))
+                return block;
+            body = { error: block.text };
+            if (/^(?:MCP error -32602: )?(?:Input validation error: )?Invalid arguments for tool /.test(block.text))
+                textCode = 'validation_failed';
+        }
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+            if (!failed)
+                return block;
+            body = { error: body };
+        }
+        if (!failed && !body.error && body.ok !== false && body.success !== false && body.valid !== false
+            && !(Array.isArray(body.errors) && body.errors.length) && !(body.status >= 400))
+            return block;
+        failed = true;
+        // An existing code is a frozen client surface, even when it is unfamiliar.
+        if ('code' in body)
+            return block;
+        const nestedCode = body.error && typeof body.error === 'object' ? body.error.code : undefined;
+        const nestedClass = typeof nestedCode === 'string' ? nestedCode.toLowerCase() : undefined;
+        const code = textCode ?? (TOOL_ERROR_CODES.includes(nestedClass) ? nestedClass
+            : (body.status === 404 ? 'not_found'
+                : body.status === 409 ? 'conflict' : body.status === 422 ? 'validation_failed'
+                    : body.status === 401 || body.status === 403 ? 'forbidden' : 'internal_error'));
+        return { ...block, text: JSON.stringify({ ...body, code }, null, block.text.includes('\n') ? 2 : undefined) };
+    });
+    if (failed && !content.some(block => block.type === 'text')) {
+        content.push({ type: 'text', text: JSON.stringify(mapDbError(undefined)) });
+    }
+    return failed ? { ...result, isError: true, content } : result;
+}
+/** SDK, HTTP and gateway registration share the same exception/refusal boundary. */
+export function withToolErrors(handler) {
+    return async (...args) => {
+        try {
+            return codedToolResult(await handler(...args));
+        }
+        catch (error) {
+            if (error instanceof McpError && error.code === ErrorCode.UrlElicitationRequired)
+                throw error;
+            return dbErrorResult(error);
+        }
+    };
+}
+const installedBoundaries = new WeakSet();
+/** Include SDK validation, which runs before registered tool handlers. */
+export function installToolErrorBoundary(server) {
+    if (!server.server || installedBoundaries.has(server.server))
+        return;
+    installedBoundaries.add(server.server);
+    const register = server.server.setRequestHandler.bind(server.server);
+    // Intercept the SDK's public registration method before its first registerTool.
+    // Other MCP methods and protocol exceptions (including URL elicitation) pass through.
+    server.server.setRequestHandler = ((schema, handler) => register(schema, schema === CallToolRequestSchema
+        ? async (...args) => codedToolResult(await handler(...args))
+        : handler));
+}

package/build/server.js

@@ -1,3 +1,4 @@
+import { withToolErrors, toolError, installToolErrorBoundary } from './lib/db-error.js';
 import { installApprovalCapabilityProbe } from './lib/approval-capabilities.js';
 import { installApprovalApp } from './lib/approval-app.js';
 import { runWithApprovalElicitation } from './lib/approval-elicitation.js';
@@ -343,13 +344,13 @@ function createScopeProxy(server, scopes, toolGroup, allowedTools) {
                         const guardedHandler = (...args) => {
                             if (!allowed()) {
                                 const text = agent ? agentConnectionRefusal(name) : tester ? testerConnectionRefusal(name) : `Forbidden: this action requires "${required}" scope.`;
-                                return { content: [{ type: 'text', text }] };
+                                return toolError({ error: text, code: 'forbidden' });
                             }
                             return runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)), scopes);
                         };
-                        return target.registerTool(name, config, guardedHandler);
+                        return target.registerTool(name, config, withToolErrors(guardedHandler));
                     }
-                    return target.registerTool(name, config, (...args) => runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args))));
+                    return target.registerTool(name, config, withToolErrors((...args) => runWithToolContext(toolGroup, name, () => runWithApprovalElicitation(target, args[1], () => handler(...args)))));
                 };
             }
             return Reflect.get(target, prop, receiver);
@@ -369,6 +370,7 @@ export const SENDINEL_SERVER_INSTRUCTIONS = [
     'On the hosted connection, any tool call (and invoke_tool) also accepts an optional project_id to act on one project for that call only; it is checked each time, and approval-gated tools require it when the connection was switched to another project. In gateway mode, find tools with search_tools (plain words work, for example "send email" or "last campaign"), check arguments with describe_tool, then call invoke_tool.',
 ].join(' ');
 export function registerAllTools(server, options) {
+    installToolErrorBoundary(server);
     if (server.server)
         installApprovalCapabilityProbe(server.server);
     // Registry callers pass scopes only: the hosted decision bridge is never enabled from a catalog.

package/build/tools/ab-testing.js

@@ -2,6 +2,7 @@ import { withApproval } from '../lib/action-approvals.js';
 import { z } from 'zod';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
+import { dbToolError } from '../lib/db-error.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 export function registerAbTestingTools(server) {
@@ -79,7 +80,7 @@ export function registerAbTestingTools(server) {
             .select()
             .single();
         if (createErr)
-            return txt(`Error: ${createErr.message}`);
+            return txt(`Error: ${dbToolError(createErr).error}`);
         return j({
             ...test,
             variant_steps: steps,
@@ -113,7 +114,7 @@ export function registerAbTestingTools(server) {
             q = q.eq('status', status);
         const { data, error } = await q;
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         return j(data);
     });
     server.registerTool('check_ab_significance', {
@@ -156,7 +157,7 @@ export function registerAbTestingTools(server) {
             .schema('email')
             .rpc('check_ab_significance', { p_test_id: test_id });
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         return j(data);
     });
     server.registerTool('promote_ab_winner', {

package/build/tools/advisor.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
-import { toolError } from '../lib/db-error.js';
+import { toolError, dbToolError } from '../lib/db-error.js';
 import { buildVoicePrompt } from '../lib/voice.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { dkimRemediationText } from '../lib/email-provider.js';
@@ -50,7 +50,7 @@ export function registerAdvisorTools(server) {
         const since = new Date(Date.now() - 30 * 86400000).toISOString();
         const { data: campaigns, error } = await db().from('campaigns').select('id, name, type').eq('project_id', projectId).eq('status', 'active').limit(200);
         if (error)
-            return j({ error: error.message });
+            return j(dbToolError(error));
         const recommendations = [];
         let skipped = 0;
         for (const campaign of campaigns ?? []) {

package/build/tools/ai-work.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
+import { dbToolError } from '../lib/db-error.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 const workItemSelect = [
@@ -85,7 +86,7 @@ async function updateWorkItemStatus(id, status, snoozedUntil) {
         .select(workItemSelect)
         .maybeSingle();
     if (error)
-        return { error: error.message };
+        return { ...dbToolError(error) };
     if (!data)
         return { error: 'AI work item not found.' };
     return { work_item: data };
@@ -130,7 +131,7 @@ async function submitContextEvent(input) {
         .eq('idempotency_key', input.idempotency_key)
         .maybeSingle();
     if (existing.error)
-        return { error: existing.error.message };
+        return { ...dbToolError(existing.error) };
     if (existing.data)
         return { context_event: existing.data, work_item: null, proposals: [], idempotent: true };
     const orgId = await getOrgIdForProject(projectId);
@@ -159,12 +160,12 @@ async function submitContextEvent(input) {
             .eq('idempotency_key', input.idempotency_key)
             .maybeSingle();
         if (duplicate.error)
-            return { error: duplicate.error.message };
+            return { ...dbToolError(duplicate.error) };
         if (duplicate.data)
             return { context_event: duplicate.data, work_item: null, proposals: [], idempotent: true };
     }
     if (inserted.error)
-        return { error: inserted.error.message };
+        return { ...dbToolError(inserted.error) };
     const event = inserted.data;
     const segmentAction = segmentActionFromContext(input.event_type, input.suggested_actions, input.title, input.detail);
     const proposals = [];
@@ -200,7 +201,7 @@ async function submitContextEvent(input) {
             .select(proposalSelect)
             .single();
         if (error)
-            return { error: error.message };
+            return { ...dbToolError(error) };
         proposals.push(proposal);
     }
     const proposalIds = proposals.map((proposal) => proposal.id);
@@ -228,7 +229,7 @@ async function submitContextEvent(input) {
         .select(workItemSelect)
         .single();
     if (workError)
-        return { error: workError.message };
+        return { ...dbToolError(workError) };
     const { data: updatedEvent, error: updateError } = await db()
         .from('ai_context_events')
         .update({ work_item_id: workItem.id, proposal_ids: proposalIds })
@@ -237,7 +238,7 @@ async function submitContextEvent(input) {
         .select('*')
         .single();
     if (updateError)
-        return { error: updateError.message };
+        return { ...dbToolError(updateError) };
     return { context_event: updatedEvent, work_item: workItem, proposals, idempotent: false };
 }
 export function registerAiWorkTools(server) {
@@ -267,7 +268,7 @@ export function registerAiWorkTools(server) {
             query = query.contains('surfaces', [surface]);
         const { data, error } = await query;
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         return j({ work_items: data ?? [] });
     });
     server.registerTool('get_ai_work_item', {
@@ -290,7 +291,7 @@ export function registerAiWorkTools(server) {
             .eq('id', work_item_id)
             .maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!data)
             return txt('AI work item not found.');
         return j({ work_item: data });
@@ -318,7 +319,7 @@ export function registerAiWorkTools(server) {
             .order('generated_at', { ascending: false })
             .limit(limit ?? 25);
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         const proposalIds = [...new Set((workItems ?? []).flatMap((item) => Array.isArray(item.proposal_ids) ? item.proposal_ids : []))];
         let proposals = [];
         if (proposalIds.length) {
@@ -328,7 +329,7 @@ export function registerAiWorkTools(server) {
                 .eq('project_id', getProjectId())
                 .in('id', proposalIds);
             if (proposalResult.error)
-                return txt(`Error: ${proposalResult.error.message}`);
+                return txt(`Error: ${dbToolError(proposalResult.error).error}`);
             proposals = proposalResult.data ?? [];
         }
         return j({ work_items: workItems ?? [], proposals });
@@ -429,7 +430,7 @@ export function registerAiWorkTools(server) {
             query = query.eq('target_id', target_id);
         const { data, error } = await query;
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         return j({ proposals: data ?? [] });
     });
     server.registerTool('get_agent_proposal', {
@@ -452,7 +453,7 @@ export function registerAiWorkTools(server) {
             .eq('id', proposal_id)
             .maybeSingle();
         if (error)
-            return txt(`Error: ${error.message}`);
+            return txt(`Error: ${dbToolError(error).error}`);
         if (!data)
             return txt('Agent proposal not found.');
         return j({ proposal: data });